问题描述
我有一个 git 存储库,其中包含多个遵循命名空间的包(即 PEP 420。
我正在尝试使用 Sphinx 创建 ReadTheDocs 文档。
git 仓库看起来像这个仓库:https://github.com/pypa/sample-namespace-packages
为了在我的本地机器上进行测试,我使用了 Sphinx 的 docker 镜像 sphinxdoc/sphinx
。
我尝试使用不同的方法为我的所有包生成文档,但每种方法最终都会遇到不同的问题。
sphinx-apidoc
docker run -it -v
密码:/repo --rm rtd bash -c 'make clean && rm -rf /repo/docs/_source/* && sphinx-apidoc -F -o /repo/docs/_source /repo && make html'
这样做的问题是它会生成错误的包,因为 sphinx-apidoc
使用子文件夹生成包,这是错误的。这将最终得到 pkg_resourcespkg_a.example_pkg.a
,它不存在,实际上应该是 example_pkg.a
autoapi.extension
# conf.py
def install(package):
subprocess.check_call([sys.executable,"-m","pip","install",package,"--no-deps"])
rootfolder=os.path.abspath('../')
add_module_names = False
autoapi_dirs = []
pathlist = Path(rootfolder).glob('repo-*/repo/*/')
for path in pathlist:
path_in_str = str(path)
autoapi_dirs.append(path_in_str)
print(path_in_str)
...
...
extensions = [
'sphinx.ext.napoleon','sphinx.ext.autosummary','sphinx.ext.autodoc','sphinx.ext.viewcode','sphinx.ext.coverage','autoapi.extension','sphinx_rtd_theme',]
autoapi_type = 'python'
autodoc_mock_imports = [
'tensorflow','flask','numpy','plotly','tqdm','StringIO','lime','vis','efficientnet_pytorch','pycocotools','repo.trainer.self_trainer_model','theano','sklearn','torch','telegram','msvcrt','bs4','livereload','repo.common.config','plotting_server','experiments','cropper',"anytree","skimage"
]
我也试过这个,但不幸的是,这最终没有在 HTML 中显示我的包的任何信息,同时还抛出以下警告:
/repo/docs/autoapi/repo/data/characteristics/detection/kmeanBoxes/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/data/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/data_structure/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/detection/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/generators/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/inference/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/mine/repo_eye_naveyaar/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/mine/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/mine/miner_vieweryoungweedscropped/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/trainer/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/utils/dataset_specific/repoeyeweedsbackgrounds/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/utils/dataset_specific/repoeyeweedslabdetection/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repo/utils/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repocommon/repo/common/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repodatasets/repo/data_sets/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repometrics/repo/metrics/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repomodels/repo/models/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/repooptimizers/repo/optimizers/index.rst: WARNING: document isn't included in any toctree
/repo/docs/autoapi/index.rst: WARNING: document isn't included in any toctree
那么,我的问题是是否可以使用 sphinx-apidoc 在同一个 git 存储库中为多个包创建文档?
解决方法
经过一番挖掘后,我发现在发布我的问题时有一些我不清楚的事情:
-
sphinx-apidoc
仅限于 python,使用起来可能会很棘手,因为它实际上导入了 python 代码,这可能需要安装依赖项或使用autodoc_mock_imports
模拟它们。 -
sphinx-autoapi
适用于 its documentation 中所述的更多编程语言,并且不需要安装依赖项。
但是,为了使用 sphinx-apidoc 或 sphinx-autoapi 在同一个 git 存储库中为多个包创建文档,我必须将以下代码添加到 docs/conf.py
:
from glob import glob
from distutils.dir_util import copy_tree
currentfolder = os.path.abspath('./') # aka docs/
rootfolder = os.path.abspath('../')
tmpfolder = "{}/tmp".format(currentfolder)
globdir = '{}/repo-*/repo'.format(rootfolder)
subprocess.check_call(["mkdir","-p",tmpfolder]) # make sure temporary folder exists
all_sub_dir_paths = glob(globdir) # returns list of sub directory paths
for subdir in all_sub_dir_paths:
print("subdir: {} to tmp folder: {}".format(subdir,tmpfolder))
copy_tree(subdir,tmpfolder) # copy all folders to docs/tmp/repo/*
autoapi_dirs = [tmpfolder]
sys.path.insert(0,tmpfolder)
autoapi_python_use_implicit_namespaces = True
此方案会将 repo 中的所有包复制到一个临时文件夹中,这将允许 docstring 工具扫描然后生成相关文档。
我最终使用了 sphinx-autoapi,但它也适用于 sphinx-apidoc,这可能需要您安装这些软件包:
def install(package):
subprocess.check_call([sys.executable,"-m","pip","install",package,"--no-deps"])
def list_files(dir):
r = []
for root,dirs,files in os.walk(dir):
for name in dirs:
if name.startswith('repo-'):
l = "{}".format(os.path.join(root,name))
# print("Added to path: {}".format(l))
sys.path.insert(0,l)
install(l) # might no be required
break # stop os.walk recurssion
return r
list_files(currentfolder)
autodoc_mock_imports = [
'tensorflow','flask',]
您可以使用 docker 在本地调试:
docker run -it -v `pwd`:/repo --rm rtd bash -c 'python -m sphinx -T -E -d _build/doctrees-readthedocs -D language=en . _build/html'
如果您使用的是 ReadTheDocs Business,您所要做的就是将您的代码推送到相关分支,其余的工作会自动为您完成。