[Python] Is it possible to create docs for multiple packages within the same git repository...

I have a git repository which includes multiple packages which follow a namespace (i.e PEP 420.

I am trying to create a ReadTheDocs documentation using Sphinx.

The git repository looks like this repo: https://github.com/pypa/sample-namespace-packages

In order to test this on my local machine, I'm using Sphinx's docker image sphinxdoc/sphinx.

I have tried to use different ways to generate the documentation for all of my packages, but each ends up with a different problem.

sphinx-apidoc


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'

The problem with this is that it will generate wrong packages as sphinx-apidoc uses the subfolders to generate the packages, which is wrong. This will end up with pkg_resourcespkg_a.example_pkg.a which does not exist and should actually be 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"
]


I have also tried this, but unfortunately, this ends up without showing anything about my packages in the HTML while also throwing the following warnings:

/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


So, my question is if it is possible to create docs for multiple packages within the same git repository with sphinx-apidoc?

Continue reading...