Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improvement [docs]: Build API reference docs with sphinx #573

Open
ryandeivert opened this issue Jan 17, 2018 · 0 comments

Comments

@ryandeivert
Copy link
Contributor

commented Jan 17, 2018

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) 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.

The good news is, there is a sphinx extension by the name of sphinxcontrib.napoleon 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.
  1. 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.