Как я могу заставить Sphinx autosummary генерировать полную документацию API для классов, а также * сводную таблицу * для этих классов? - PullRequest
Новая
       60

Как я могу заставить Sphinx autosummary генерировать полную документацию API для классов, а также * сводную таблицу * для этих классов?

0 голосов
/ 03 мая 2020

Я уверен, что это ошибка пользователя на том или ином уровне, но я медленно схожу с ума и буду очень признателен за помощь.

Я получил как sphinx-apidoc, так и отличную стороннюю организацию sphinx-autoapi, но не могу повторить трюк с sphinx.ext.autosummary. Это сводит меня с ума ... плюс ни одна из этих опций не дает вам действительно аккуратных сводных таблиц элементов пакета / модуля, которые (предположительно) являются основным преимуществом sphinx.ext.autosummary.

У меня действительно простой проект: 

|_ TEST
   |_ docs
      |_ conf.py
      |_ index.rst
   |_ myproject
      |_ __init__.py
      |_ mymodule.py

conf.py выглядит так: 

import os
import sys
sys.path.insert(0, os.path.abspath('../../myproject'))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary'
]

autosummary_generate = True

index.rst выглядит так: 

.. autosummary::
   :toctree: _autosummary

   myproject.mymodule

mymodule.py выглядит так: 

"""
Module containing a class and a function.
"""

class TestClass:
    """
    A class representing a test.

    I wish I could get this to stuff to show up but I can't and I don't know why.

    Why isn't this documentation visible?!? :-(
    """
    def __init__(self):
        """
        Instantiate.
        """
        pass

    def Func_in_test_class(self):
        """
        Cool function that does stuff.

        :return: Some new stuff.
        """
        pass

def GlobalFunc():
    """
    Utility function.

    Does some good stuff.
    """
    pass

Запуск make html из каталога docs делает этот прекрасный стиль Readthedocs HTML:

(see picture)

Что я хочу сделать, это нажать на функцию TestClass в сводной таблице и перейти на новую страницу, на которой полностью показана документация API для этого класса. Как мне этого добиться?

(Или я упускаю суть, и мне нужно объединить sphinx.ext.autosummary с sphinx-apidoc, чтобы получить то, что мне нужно ..?)

...