我有一个git存储库,它包含多个遵循名称空间(即PEP 420)的包
我正在尝试使用Sphinx创建ReadTheDocs文档
git存储库看起来像这样的repo:https://github.com/pypa/sample-namespace-packages
为了在本地机器上测试这一点,我使用了Sphinx的docker imagesphinxdoc/sphinx
我曾尝试使用不同的方法为我的所有包生成文档,但每种方法都会产生不同的问题
docker run -it -v
pwd:/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
# 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
:此解决方案将把回购协议中的所有包复制到一个临时文件夹中,该文件夹将允许docstring工具扫描并生成相关文档
我最终使用了sphinx autoapi,但它也可以与sphinx apidoc一起使用,这可能需要您安装以下软件包:
您可以使用docker在本地调试:
如果您使用的是ReadTheDocs业务,那么您所要做的就是将代码推送到相关分支,其余的工作将自动为您完成
相关问题 更多 >
编程相关推荐