4 ms·

Which plugin do you use to go docstring->docs? I found it difficult out of the box to determine w/ Sphinx how to get everything to play nice.

susam 7y ago
I use sphinx-apidoc[1] command to extract docstrings from code and create Sphinx documentation files out of them. Enter this command to look for modules in a package, say, foopkg, and create .rst files to generate documentation for each module in the package and subpackages: sphinx-apidoc --module-first -o docs/api foopkg I am assuming that the Sphinx documentation project resides in a directory named docs. Each .rst file would contain automodule directives for Sphinx to automatically pull docstrings from foopkg and render them in the generated documentation. However, for Sphinx to understand these automodule directives, the autodoc[2] extension must be enabled in docs/conf.py. extensions = ['sphinx.ext.autodoc'] If the documentation is written using Google style or NumPy style docstrings, then the napolean[3] extension must also be enabled. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'] The sphinx-apidoc command above would also write a file named docs/api/modules.rst which would be used to render the starting page of the automatically generated API documentation. So include this docs/api/modules.rst with the Sphinx toctree directive from the some other page that the user is likely to visit. For example, the start page of the project documentation would likely be rendered from `docs/index.rst`, so add this to `docs/index.rst`: API --- .. toctree:: api/modules Now render the documentation with Sphinx normally: cd docs && make html [1]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html [2]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html [3]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html https://www.sphinx-doc.org/en/master/usage/extensions/napole...

susam 7y ago

I use sphinx-apidoc[1] command to extract docstrings from code and create Sphinx documentation files out of them. Enter this command to look for modules in a package, say, foopkg, and create .rst files to generate documentation for each module in the package and subpackages: sphinx-apidoc --module-first -o docs/api foopkg I am assuming that the Sphinx documentation project resides in a directory named docs. Each .rst file would contain automodule directives for Sphinx to automatically pull docstrings from foopkg and render them in the generated documentation. However, for Sphinx to understand these automodule directives, the autodoc[2] extension must be enabled in docs/conf.py. extensions = ['sphinx.ext.autodoc'] If the documentation is written using Google style or NumPy style docstrings, then the napolean[3] extension must also be enabled. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'] The sphinx-apidoc command above would also write a file named docs/api/modules.rst which would be used to render the starting page of the automatically generated API documentation. So include this docs/api/modules.rst with the Sphinx toctree directive from the some other page that the user is likely to visit. For example, the start page of the project documentation would likely be rendered from `docs/index.rst`, so add this to `docs/index.rst`: API --- .. toctree:: api/modules Now render the documentation with Sphinx normally: cd docs && make html [1]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html [2]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html [3]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html https://www.sphinx-doc.org/en/master/usage/extensions/napole...