How can I make sphinx-quickstart auto-include docstrings from my Python modules

0
votes

I am trying out Sphinx for generating documentation for a Python project. Just to make sure I can actually make it work, I have made a test project to try it out on: https://github.com/ThomasA/sphinxtest.

I have run sphinx-quickstart in the root of this repository. In the following questions, I specified 'doc' as the documentation root, named the project 'sphinxtest', entered 'Thomas Arildsen' as author, answered 'y' to the 'autodoc' option, and selected the default setting for everything else.

I expected the 'autodoc' option to cause the generation of a file 'amodule.rst' in the 'doc' folder. However, this does not get generated. I am puzzled by this. I thought this was what the 'autodoc' option was supposed to do and what I have seen examples of others apparently achieve with it. Sphinx completes without any error messages, so it seems to be doing what it thinks it should do. So, what could I be doing wrong?

I am using Sphinx v. 1.5.6 and Python 3.5.3, all installed with Anaconda.

2
pythonpython-sphinx

2 Answers

1
votes

autodoc does not generate the .rst source files.

Instead first use sphinx-apidoc to generate the source files. Then run Sphinx to make your documentation.

0
votes

An alternative to Percy's answer is autoapi written by Carlos Jenkins. He provides a Sphinx extension that generates the ReST files per documentation generation. You can configure the output ReST by modifying a template file.

https://github.com/carlos-jenkins/autoapi