Skip to main content

Best practices for documenting a scientific Python project

Publication Type
Conference Paper
Book Title
US-RSE23 Conference Proceedings
Publication Date
Conference Name
Annual Conference of the US Research Software Engineer Association (US-RSE 2023)
Conference Location
Chicago, Illinois, United States of America
Conference Sponsor
US Research Software Engineer Association (US-RSE)
Conference Date

Documentation is a crucial component of software development that helps users with installation and usage of the software. Documentation also helps onboard new developers to a software project with contributing guidelines and API information. The INTERSECT project is an open federated hardware/software library to facilitate the development of au- tonomous laboratories. A documentation strategy using Sphinx has been utilized to help developers contribute to source code and to help users understand the INTERSECT Python interface. Docstrings as well as reStructuredText files are used by Sphinx to automatically compile HTML and PDF files which can be hosted online as API documentation and user guides. The resulting documentation website is automatically built and deployed using GitLab runners to create Docker containers with NGINX servers. The approach discussed in this paper to automatically deploy documentation for a Python project can improve the user and developer experience for many scientific projects.