Best practices for documenting a scientific Python project

Conference · Fri Dec 01 04:00:00 EST 2023

OSTI ID:2305819

Wiggins, Gavin ^[1]; Cage, Gregory ^[1]; Smith, Robert ^[1]; Hitefield, Seth ^[1]; McDonnell, Marshall ^[1]; Drane, Lance ^[1]; McGaha, Jesse ^[1]; Brim, Michael ^[1]; Abraham, Mark ^[1]; Archibald, Richard ^[1]; Malviya Thakur, Addi ^[1]

---

1. ORNL

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.

• Research Organization: Oak Ridge National Laboratory (ORNL), Oak Ridge, TN (United States)
• Sponsoring Organization: USDOE
• DOE Contract Number: AC05-00OR22725
• OSTI ID: 2305819
• Country of Publication: United States
• Language: English