我已经创建了一个使用setuptools的demo项目,其结构如下:
project/
|- pizza/
| |- __init__.py
| `- margherita.py
|
|- README.rst
|- setup.cfg
`- setup.py
我正在尝试使用Sphinx为这个项目自动生成文档。到目前为止,我已经尝试过:
# Generate a sphinx template
sphinx-quickstart
# Use default settings, except for project name, etc.
sphinx-apidoc -o source .
./setup.py build_sphinx
我觉得必须有一种更简单的方法来使用README
、setup.py
和文档字符串自动生成该文档。
最终,我希望为另一个我也使用Python C-api的项目自动生成apidocs。我找不到任何关于这个的东西。
我的主要问题是:有没有一种更简单的方法来自动生成这个文档?
发布于 2014-03-09 02:17:27
要扩展setup.py
,使其包含一个用于Sphinx的额外命令,您可以创建一个自定义命令。我编写了一个小示例,运行Sphinx apidoc,然后构建文档源代码。使用在setup.py
中定义的源代码的项目名称、作者、版本和位置(假设它们已定义)。
class Sphinx(Command):
user_options = []
description = 'sphinx'
def initialize_options(self):
pass
def finalize_options(self):
pass
def run(self):
# metadata contains information supplied in setup()
metadata = self.distribution.metadata
# package_dir may be None, in that case use the current directory.
src_dir = (self.distribution.package_dir or {'': ''})['']
src_dir = os.path.join(os.getcwd(), src_dir)
# Run sphinx by calling the main method, '--full' also adds a conf.py
sphinx.apidoc.main(
['', '--full', '-H', metadata.name, '-A', metadata.author,
'-V', metadata.version, '-R', metadata.version,
'-o', os.path.join('doc', 'source'), src_dir])
# build the doc sources
sphinx.main(['', os.path.join('doc', 'source'),
os.path.join('doc', 'build')])
然后需要将该命令注册到入口点组distutils.commands
。这里的命令名为sphinx
。
from setuptools import setup
setup(
# ...
setup_requires = ['sphinx'],
entry_points = {
'distutils.commands': [
'sphinx = example_module:Sphinx'
]
}
)
我不知道C源代码是如何处理的,但这将帮助您入门。
https://stackoverflow.com/questions/21149035
复制相似问题