Documenting multiple Python packages on one Sphinx page

问题

I'm trying to create Sphinx documentation for several Python packages. I've been able to make a main page that lists the two packages I've made, like so:

However, when I click through either of the packages, The modules are listed, but without any of their docstrings/documentation:

When I make documentation for one of the folders (data-analytics-bc3-api, for example), I can make a single page without issue, following the instructions here. However, when I try to make one page that covers multiple packages, I have issues.

I've set up my directory structure as follows:

master-api-docs/
    data-analytics-admin-lambda/
        __init__.py
        create_password_link.py
        ...
    data-analytics-bc3-api/
        __init__.py
        basecamp_api_call.py
        ...

The __init__.py files are empty, I made them so Sphinx would think their corresponding folders are packages.

My conf.py file has the following changes:

import os
import sys
sys.path.insert(0, os.path.abspath('./data-analytics-admin-lambda'))
sys.path.insert(0, os.path.abspath('./data-analytics-bc3-api'))

extensions = [
'sphinx.ext.napoleon',
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.viewcode',
]

html_theme = 'sphinx_rtd_theme'

And to initialize and create the documenation I run the following:

$ cd master-api-docs
$ sphinx-quickstart (No on separating build and source, yes on autodoc, yes on Makefile)
$ sphinx-apidoc -o . .

Here I edit index.rst to include modules in the toctree section.

$ make html

This generates many instances of the warning:

WARNING: invalid signature for automodule ('data-analytics-admin-lambda.check_cta_email')
WARNING: don't know which module to import for autodocumenting 'data-analytics-admin-lambda.check_cta_email' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: invalid signature for automodule ('data-analytics-admin-lambda.create_aws_user')
WARNING: don't know which module to import for autodocumenting 'data-analytics-admin-lambda.create_aws_user' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)

My index.rst file looks like this:

.. Data Analytics API Documentatin documentation master file, created by
   sphinx-quickstart on Tue Mar 19 16:04:45 2019.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Data Analytics API Documentatin's documentation!
===========================================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

modules.rst looks like this:

master-api-docs
===============

.. toctree::
   :maxdepth: 4

   data-analytics-admin-lambda
   data-analytics-bc3-api

And my data-analytics-admin-lambda.rst looks like this, for reference:

data\-analytics\-admin\-lambda package
======================================

Submodules
----------

data\-analytics\-admin\-lambda.check\_cta\_email module
-------------------------------------------------------

.. automodule:: data-analytics-admin-lambda.check_cta_email
    :members:
    :undoc-members:
    :show-inheritance:

data\-analytics\-admin\-lambda.create\_aws\_user module
-------------------------------------------------------

.. automodule:: data-analytics-admin-lambda.create_aws_user
    :members:
    :undoc-members:
    :show-inheritance:

Why is this? Is it possible to document multiple Python packages on one Sphinx page?

来源：https://stackoverflow.com/questions/55245586/documenting-multiple-python-packages-on-one-sphinx-page

标签

python-3.x

documentation

python-sphinx