Improvement [docs]: Build API reference docs with sphinx
- Dominant language
- Python
- Stars
- 2.9k
- Forks
- 324
- PR merge metrics
- No merged PRs in 30d
Description
## Background
Determine whether it would be beneficial to build reference documentation with sphinx that could get published on RTD.
### Description
Other projects publish reference guides (see: [here](https://margaritashotgun.readthedocs.io/en/latest/reference_guide.html)) that can be helpful for users to both understand the code base and to use your modules more easily.
The main difference between our project and the one linked to is that we have chosen to use Google style docstrings in lieu of the [Sphinx style docstrings](https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions).
The good news is, there is a sphinx extension by the name of [sphinxcontrib.napoleon](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html) that adds support for parsing Google style docstrings to build reference docs.
## Desired Change
1. Clean up the code base so that:
* [ ] Only methods or properties that should be publicly accessible on a class are defined as such. All methods/properties that should **not** have an external interface should be prefixed with `_`. In most of our classes, the vast majority of the methods can be converted to protected or private, as there are very few functions that need to be accessible outside of the class itself.
* [ ] All public method docstrings are complete and accurate.
2. Generate reference docs on the most relevant classes/methods that users may interact with using a combination of our current sphinx documentation and the `sphinxcontrib.napoleon` extension. We can choose what modules get docs generated for them through the rst `.. automodule::` directive.
Contributor guide
Research direction
Start by reviewing the project's current Sphinx documentation and the classes and methods whose public interfaces would need documenting. Determine which methods and properties should remain public, complete their Google-style docstrings, and use sphinxcontrib.napoleon with rst automodule directives to generate reference documentation for the selected classes and methods.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100