Документирование нескольких пакетов Python на одной странице Sphinx - PullRequest
Новая
       26

Документирование нескольких пакетов Python на одной странице Sphinx

0 голосов
/ 19 марта 2019

Я пытаюсь создать документацию Sphinx для нескольких пакетов Python. Мне удалось создать главную страницу, в которой перечислены два пакета, которые я сделал, например:

Documentation Main Page

Однако, когда я щелкаю по любому из пакетов, модули отображаются в списке, но без какой-либо из их строк документации / документации: Modules without documentation

Когда я делаю документацию для одной из папок (например, data-analytics-bc3-api), я могу без проблем создать одну страницу, , следуя приведенным здесь инструкциям . Однако, когда я пытаюсь создать одну страницу, охватывающую несколько пакетов, у меня возникают проблемы.

Я настроил структуру каталогов следующим образом: 

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

Файлы __init__.py пусты, я сделал их так, чтобы Sphinx считал их соответствующие папки пакетами.

Мой файл conf.py содержит следующие изменения: 

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'

И чтобы инициализировать и создать документацию, я запускаю следующее: 

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

Здесь я редактирую index.rst, чтобы включить modules в раздел toctree. 

$ make html

Это генерирует много экземпляров предупреждения: 

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)

Мой index.rst файл выглядит так: 

.. 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 выглядит так: 

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

.. toctree::
   :maxdepth: 4

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

А мой data-analytics-admin-lambda.rst выглядит вот так, для справки: 

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:

Почему это? Можно ли документировать несколько пакетов Python на одной странице Sphinx?

...