使用Sphinx的sphinx-apidoc实用程序从python代码自动生成文档 [英] using Sphinx's sphinx-apidoc utility to autogenerate documentation from python code

问题描述

我想知道注释格式是什么，以便使用Sphinx的sphinx-apidoc实用程序编写自记录代码.我能够使用此实用程序为每个python文件生成一组reStructuredText文件，但仍需要填写这些文件.我正在寻找一种获取此实用程序的方法，或一些其他Sphinx实用程序以从中生成文档. python代码docstrings.我知道这将需要熟悉传统的注释格式，并且我希望指向该参考资料.谢谢！

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!

推荐答案

mzjn，感谢您的评论.您的第二个链接为如何设置 docstrings 格式提供了一些很好的见识.

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

此外，我未能标记正确的 sphinx-quickstart 提示答案(如链接中指定的

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:自动从模块中插入文档字符串(y/N)[n]:

http ://codeandchaos.wordpress.com/2012/07/30/sphinx-autodoc-tutorial-for-dummies/和 conf.py 注释，我需要附加以下位置:模块到系统路径.我应该注意，我在添加文件名时遇到了问题.当我将路径添加到可以找到模块的位置时，一切运行正常.

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.

这篇关于使用Sphinx的sphinx-apidoc实用程序从python代码自动生成文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！