Есть ли способ предварительно собрать файлы .rst, сгенерированные autodoc, в Sphinx

У меня есть проект, для которого я создал набор файлов .rst с sphinx.ext.apidoc, который извлекает документацию из строк документации моего проекта.

Эти файлы выглядят следующим образом:

Submodules
----------
.. toctree::
   mymodule.submodule

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

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

make html правильно создает документацию на моем компьютере, но требует, чтобы я отредактировал файл conf.py, чтобы добавить мой проект в системный путь python, чтобы он правильно находил модули, упомянутые в файлах .rst, когда autodoc пытается их импортировать.

Однако, когда я пытаюсь создать документацию на readthedocs, autodoc не может найти модули, на которые есть ссылки, потому что я не знаю, какой путь нужно добавить к системному пути python, чтобы autodoc правильно нашел модули проекта.

Мне было интересно, можно ли предварительно собрать файлы .rst с помощью autodoc в локальной среде, чтобы они больше не содержали никаких вызовов autodoc, а затем загрузить их в readthedocs, чтобы не было необходимости запускать там расширение autodoc.

Если нет способа сделать это, что будет правильным способом решения этой проблемы?


python python-sphinx autodoc read-the-docs
person chiffa    schedule 10.03.2015    source источник
comment
У вас нет setup.py, чтобы сообщить RTD и т. Д., Как установить проект?   -  person jonrsharpe    schedule 11.03.2015
comment
Вы нашли решение этой проблемы? У меня такая же проблема с проектом, основанным на Cython, поэтому (я думаю) невозможно построить на RTD.   -  person Sebastien    schedule 22.09.2015
comment
Да, тогда я написал об этом сообщение в блоге: andreikucharavy.com/L3Cache/parsing-sphinx Я обновлю ответ ниже. Основная идея - использовать макетные модули, как это предлагается здесь: docs.readthedocs.org/ ru / latest / faq.html   -  person chiffa    schedule 23.09.2015

Ответы (1)


arrow_upward
0
arrow_downward

После некоторой работы решение было предоставлено readthedocs FAQ: для модули, которые зависят от C и не могут быть легко установлены pip внутри сборок venv readthedoc, необходимо имитировать их и все подмодули, которые вы импортируете в файл conf.py в каталоге myproject/docs/source вашей документации (или там, где находится conf.py вашего Sphinx) . в моем случае код был следующим:

if on_rtd:
    warn('debug -syspath -edit: %s'%os.path.abspath('../..'))
    sys.path.insert(0, os.path.abspath('../..'))

    class Mock(MagicMock):

        @classmethod
        def __getattr__(cls, name):
            return Mock()

        @classmethod
        def __getitem__(cls, name):
            return Mock()


    MOCK_MODULES = ['numpy',
                    'scikit-learn',
                    'pymongo',
                    'cython',
                    'Cython',
                    'matplotlib',
                    'matplotlib.pyplot',
                    'scipy',
                    'scipy.stats',
                    'scipy.sparse',
                    'scipy.sparse.linalg',
                    'scipy.sparse.csgraph',
                    'scikits',
                    'scikits.sparse',
                    'scikits.sparse.cholmod',
                    'sklearn',
                    'sklearn.cluster',
                    'python-Levenshtein'
                    'levenstein',
                    'python.levenstein'
                    ]

    for mod_name in MOCK_MODULES:
        sys.modules.update({mod_name: Mock()})
person chiffa    schedule 22.09.2015