Documenting a project¶
Documenting a project is the key to make it usable, understandable and maintainable, making the difference between a technically excellent software and a successful software. SKA has defined a set of standards and practices that shall be implemented when developing software documentation. A more comprehensive set of resources can be found online at:
What to document¶
Based on the documentation provided everyone should be able to:
- understand the problem the project is trying to solve
- understand how the project is implemented
- know exactly what this projects depends on
- download and build the project
- execute the project tests
- run the project
In order to achieve this goal any structure can be used allowing free text as well as code-extracted documentation.
Documenting the Public API¶
When it comes to software systems, such as services or libraries, it is of paramount importance that the public API exposed by the software component is clearly captured and documented.
How to document¶
Documentation on git¶
Each software repository shall contain its documentation as part of the code included in a git repository. In this way the documentation will be released with the same cadence as the code and it will always be possible to trace a particular version of the documentation to a particular version of the code documented.
Free text documentation must be placed in a docs folder in the upper level of the
repository structure. Sphinx generates automatically extracted files under this folder as well, wherever there are docstrings in the code.
Using sphinx¶
Documentation must be realised using the sphinx
package and Restructured Text .
SKA provides a predefined sphinx template for this purpose in the
SKA Python skeleton project.
Every project shall use the same docs folder as a starting point for assembling their
own documentation.
Sphinx can be used to generate text documents such as this portal, but it also provides capabilities to automatically extract and parse code documentation, or docstrings. Refer to the Python Coding Guidelines for more information.
Extracting documentation from code¶
Todo
- add hello world class with parameters to the SKA Python Skeleton Project
- add code snippet here as an example of additional documentation which is decoupled from code, and describe the pitfalls of separating documentation from the code.
Integrating into the Developer Portal¶
The developer portal is hosted on ReadTheDocs. On the List of projects page a list of all the projects that are hosted on GitLab is available, with badges to show the build status of the project’s documentation. Each badge is also a hyperlink to the project’s documentation.
Every SKA project’s documentation is hosted on Readthedocs as a subproject of the developer portal, so that all projects have a common URL for easier search-ability. For example: whereas the developer portal’s URL is https://developer.skatelescope.org, the ska_python_skeleton project is at https://developer.skatelescope.org/projects/ska-python-skeleton.
In order to add the project’s documentation as a subproject on Readthedocs, a project must first be imported into Readthedocs.
Register on ReadTheDocs¶
Developers working on the SKA are members of the ska-telescope organisation on GitLab. Registering an account using the OAuth credentials on ReadTheDocs is recommended, because then the integration between the SKA GitLab and SKA ReadTheDocs services is done automatically. The integrations can also be set up manually later, and is not difficult.
Sign up / sign in with GitLab account¶
Log in with OAuth¶
As of October 2019, most developers are also registered on the SKA GitHub, and some may sign in using the OAuth credentials provided by GitHub, when signing into GitLab. This will be the preferred route.
Import project to ReadTheDocs¶
After signing in, one lands on the Dashboard, and the steps for importing a project are pretty self-explanatory from here.
Add project as a sub-project on ReadTheDocs¶
A sub-project must be added by a user with Maintainer privileges on the main project.
Currently only the System Team members have these permissions. Please ask on the Slack channel #team-system-support to have your project added.
For more information on how to add a subproject, go to Read The Docs.