Readthedocs не отображает документацию документации - PullRequest
Новая
       66

Readthedocs не отображает документацию документации

0 голосов
/ 04 октября 2018

Я следовал руководству по началу работы с Readthedocs и использовал Sphinx с помощью autodoc для создания документации для моего пакета Python на https://github.com/akdiem/bloodflow. (соответствующие файлы документации .rst находятся в папке docs)

Сборка readthedoc прошла и обнаружена на https://bloodflow.readthedocs.io/en/latest/

Readthedocs не показывает никакой документации по документации, которая является частью моего кода, но для меня все выглядит так, как должно.Почему нет?

1 Ответ

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

Autodoc - это расширение Sphinx, которое просматривает ссылки на директивы автомодуля в файлах .rst во время сборки, импортирует и идентифицирует код Python, а затем преобразует их строки документации в html.

Поскольку ваш модуль не установлен в среду с setup.py, он должен импортировать ваш модуль вручную, поэтому вам нужно задать контекст sphinx в conf.py: 

import os
import sys
#Location of Sphinx files
sys.path.insert(0, os.path.abspath('./../..'))

Inв этом случае абсолютный путь к вашему верхнему модулю на 2 уровня выше файла conf.py.

После этого вы можете добавить файл директивы autodoc arteryfe.rst обратно в индекс .rst toctrees , и он должен появиться. 

Welcome to artery.fe's documentation!
=====================================

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

    arteryfe
    getting_started
    tutorial
    theory
    numerical

В случае, если вы когда-либо захотите выполнить установку среды, вам нужно будет выбрать опцию ReadTheDocs, чтобы использоватьvirtualenvironment и использовать site-пакеты.

Приложение:

Это еще один способ сделать это и особенно полезно, если у вас более одного пакета.

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

Это означает, что вы можете запустить sphinx-apidoc с предпочтительными параметрами, и он сгенерирует файлы .rst из ваших строк документации с директивами автомодуля - которые затем сгенерируются в html.Однако это также можно сделать с помощью conf.py во время сборки в RTD.

Например, Sphinx будет генерировать файл автомодуля arteryfe.rst в /source/_autogen во время сборки: 

import os
import sys
#Location of Sphinx files
sys.path.insert(0, os.path.abspath('./../..'))

import sphinx.apidoc
def setup(app):
    sphinx.apidoc.main(['-f', #Overwrite existing files
                        '-T', #Create table of contents
                        #'-e', #Give modules their own pages
                        '-E', #user docstring headers
                        #'-M', #Modules first
                        '-o', #Output the files to:
                        './source/_autogen/', #Output Directory
                        './../arteryfe', #Main Module directory
                        ]
    )

После этого просто поместите весь вывод автогена в ваше дерево. 

Welcome to artery.fe's documentation!
=====================================

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

    getting_started
    tutorial
    theory
    numerical

.. toctree::
    :maxdepth: 2
    :glob:
    :caption: Code:

    _autogen/*

Это немного менее гибко, поскольку создание шаблонов для apidoc затруднительно.Это все еще верное решение и полезно в некоторых случаях (например, огромные кодовые базы).

Я набросал Пример, совместимый с RTD для apidoc multipackages.

...