sphinx-apidoc подбирает подмодули, но autodoc не документирует их

Question

Я работал над проектом для PyQt5 (находится здесь: https://github.com/MaVCArt/StyledPyQt5), который использует структуру пакета, чтобы сделать импорт немного более логичным. До сих пор я был относительно успешным в документировании кода с помощью Sphinx, по крайней мере до тех пор, пока я не представил структуру пакета. (раньше все было в одной папке)

Проблема заключается в следующем: когда я запускаю sphinx-apidoc, все работает нормально, без ошибок. Более того, Autodoc прекрасно подхватывает все мои подмодули. Это содержимое одного из моих.rst файлов:

styledpyqt package
==================

Subpackages
-----------

.. toctree::
    :maxdepth: 8

    styledpyqt.core

Submodules
----------

styledpyqt.StyleOptions module
------------------------------

.. automodule:: styledpyqt.StyleOptions
    :members:
    :undoc-members:
    :show-inheritance:

styledpyqt.StyleSheet module
----------------------------

.. automodule:: styledpyqt.StyleSheet
    :members:
    :undoc-members:
    :show-inheritance:


Module contents
---------------

.. automodule:: styledpyqt
    :members:
    :undoc-members:
    :show-inheritance:

Как вы можете сказать, все подмодули подобраны.

Однако, когда я запускаю make html, ни один из этих модулей не документируется (имеется в виду, что заголовки есть, но ни один из методов, классов или членов не отображается). В сгенерированном HTML они просто заголовки, в которых ничего нет. Я точно знаю, что они правильно настроены в комментариях к коду, так как код не изменился между моментом и настройкой структуры пакета, то есть, когда документация действительно работала.

У кого-нибудь есть идеи, в чем причина?

Примечание: чтобы помочь решить эту проблему, вот краткая структура моей папки:

styledpyqt
+    core
+    +    base
+    +    +    __init__.py ( containing a class definition )
+    +    +    AnimationGroups.py
+    +    +    Animations.py
+    +    __init__.py
+    +    Color.py
+    +    Float.py
+    +    Gradient.py
+    +    Int.py
+    +    String.py
+    __init__.py
+    StyleOptions.py
+    StyleSheet.py

Answer 1

В конце концов я решил эту проблему - кажется, я пропустил некоторые ошибки, и sphinx работал просто отлично. Я добавил все пути, содержащиеся в пакете, в conf.py, и он только что сработал:

conf.py:

sys.path.insert(0, os.path.abspath('../StyledPyQt5'))
sys.path.insert(0, os.path.abspath('../StyledPyQt5/styledpyqt'))
sys.path.insert(0, os.path.abspath('../StyledPyQt5/styledpyqt/core'))
sys.path.insert(0, os.path.abspath('../StyledPyQt5/styledpyqt/core/base'))

Оттуда все работало.

Здесь важно отметить, что я генерирую свои документы в отдельной директории от моего кода. Если вы используете sphinx-apidoc для генерации ваших файлов.rst и используете для документации gh-pages ветку, как я, не забудьте сгенерировать HTML-страницы отдельно, пока вы находитесь в основной ветке. В противном случае не будет никакого кода для получения. Мой рабочий процесс выглядит следующим образом:

1. убедитесь, что я в главной ветке, запустив git checkout master
2. бежать sphinx-apidoc -F -P -o ..output_dir ..source_dirгде output_dir отличается от source_dir.
3. бежать make html, убедившись, что _build / html находится в каталоге, которого нет ни в одной из веток моего репо.
4. бежать git checkout gh-pages переключиться на мою ветку gh-pages, удалив файлы кода и заменив их HTML-страницами документации.
5. скопируйте все новые сгенерированные файлы HTML в _build / html в основную папку gh-pages, перезаписав все изменения.
6. бежать git commit -am "Docs Update" gh-pages совершить изменения
7. бежать git push origin gh-pages подтолкнуть коммит к github
8. бежать git checkout master вернуть меня на главную ветку

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

Answer 2

У меня была аналогичная проблема: изменив maxdepth toctree и перестроив html, ничего не изменилось в визуализации в браузере. Я решил проблему, удалив сначала соответствующие файлы .rst и перезапустив команда. После этого я перестроил файлы html, используя . Визуализация в браузере наконец-то оказалась такой, как хотелось.