using Sphinx's sphinx-apidoc utility to autoge

问题:

I am wondering what the commenting format is in order to have self-documenting code using Sphinx's sphinx-apidoc utility. I am able to get this utility to generate a set of reStructuredText files for each python file, but these files still need to be filled in. I am looking for a way to get this utility, or some other Sphinx utility to generate documentation from the python codes docstrings. I understand this would require becoming familiar with a conventional commenting format, and I am hoping to be pointed to this reference material. Thanks!

回答1:

mzjn, thanks for the comment. your second link provided some good insight on how to format docstrings.

furthermore, i failed to mark the proper sphinx-quickstart prompt answers (as specified in the link, http://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example). particularly, answering yes to:

autodoc: automatically insert docstrings from modules (y/N) [n]:

also, as noted in the link, http://codeandchaos.wordpress.com/2012/07/30/sphinx-autodoc-tutorial-for-dummies/, and the conf.py comments, i needed to append locations of modules to the system path. i should note that i ran into a problem appending filenames. when i appended paths where modules could be found, everything worked perfectly.