是否可以使用 sphinx-apidoc 在同一 git 存储库中为多个包创建文档?

问题描述 投票:0回答:1

我有一个 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.扩展

# 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 存储库中为多个包创建文档?

python python-sphinx read-the-docs namespace-package sphinx-apidoc
1个回答
1
投票

经过相当多的挖掘,我在发布问题时发现了一些我不清楚的事情:

  1. sphinx-apidoc
    仅适用于 python,使用起来可能很棘手,因为它实际上导入了 python 代码,这可能需要安装依赖项或使用
    autodoc_mock_imports
    来模拟它们。

  2. sphinx-autoapi
    可与更多编程语言配合使用,如其文档中所述,并且不需要安装依赖项。

但是,为了使用 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

此解决方案会将存储库中的所有包复制到临时文件夹,这将允许文档字符串工具扫描并生成相关文档。

我最终使用了 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 recursion
    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,您所要做的就是将代码推送到相关分支,其余的将会自动为您完成。

© www.soinside.com 2019 - 2024. All rights reserved.