USRSE23 Conference Proceedings
Published December 22, 2023 | Version v1
Conference paper Open

Best practices for documenting a scientific Python project

Creators

  • 1. Oak Ridge National Laboratory

Description

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. Without the right tools, generating documentation can be laborious and distract from code development. The INTERSECT SDK project is an open federated hardware/software library to facilitate the development of autonomous laboratories. A documentation strategy using Sphinx has been utilized to help developers contribute to the source code and help users understand the INTERSECT SDK Python interface. Docstrings as well as reStructuredText files are used by Sphinx to generate 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.

Files

paper_53_US-RSEcon2023_revised240120.pdf

Files (1.0 MB)