Строки документации не включены в сборку Read the Docs Sphinx.

Я создал документацию Sphinx, и эта сборка хорошо работает локально. Мои строки документации выглядят так, как показано ниже.

введите здесь описание изображения

При переходе на readthedoc.io я добавил конкретный файл требований в docs/requirement.txt, а именно:

sphinx==3.5.4
sphinx_rtd_theme==0.5.2
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==1.0.3
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.4

И мой .readthedocs.yaml выглядит так:

# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
sphinx:
   configuration: docs/source/conf.py

# Optionally build your docs in additional formats such as PDF
formats:
   - pdf

# Optionally set the version of Python and requirements required to build your docs
python:
   version: 3.7
   install:
    - requirements: docs/requirements.txt

Однако при сборке документа на readthedocs.io, даже если моя сборка завершается без ошибок, строки документации не отображаются. введите здесь описание изображения

Вот журнал:

git clone --no-single-branch --depth 50 https://github.com/Green-Investement-Dashboard/GRID_app.git .
git checkout --force origin/app_v2
git clean -d -f -f
python3.7 -mvirtualenv /home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m pip install --upgrade --no-cache-dir pip setuptools
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m pip install --upgrade --no-cache-dir mock==1.0.1 pillow==5.4.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.8.1 recommonmark==0.5.0 sphinx sphinx-rtd-theme readthedocs-sphinx-ext<2.2
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m pip install --exists-action=w --no-cache-dir -r docs/requirements.txt
cat docs/source/conf.py
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m sphinx -T -b html -d _build/doctrees -D language=en . _build/html
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m sphinx -b latex -D language=en -d _build/doctrees . _build/latex
cat latexmkrc
latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=grid-app -interaction=nonstopmode
mv -f /home/docs/checkouts/readthedocs.org/user_builds/grid-app/checkouts/latest/docs/source/_build/latex/grid-app.pdf /home/docs/checkouts/readthedocs.org/user_builds/grid-app/artifacts/latest/sphinx_pdf/grid-app.pdf

Что я сделал не так?


python python-sphinx autodoc read-the-docs
person clematologie    schedule 11.05.2021    source источник

Ответы (2)


arrow_upward
1
arrow_downward

Помните, что расширение Sphinx Autodoc импортирует модули, задокументировано. Это потому, что Autodoc использует самоанализ Python для доступа к строкам документации. Преимущество этого с точки зрения Autodoc состоит в том, что Python может выполнять синтаксический анализ. Недостаток, с точки зрения пользователя, заключается в том, что мы должны убедиться, что все зависимости установлены или, по крайней мере, смоделированы.

Это не проблема на вашей машине разработки, где, естественно, все внешние библиотеки, от которых зависит ваш пакет, уже установлены. Но при сборке на сервере Read-the-Docs, так сказать, в голой среде Python многие из них отсутствуют. Вы добавили зависимости, необходимые для сборки проекта Sphinx, в docs/requirements.txt, и этого было бы достаточно, если бы вы не использовали расширение Autodoc. Но поскольку вы это делаете, ваши строки документов отсутствуют, потому что модули в вашем пакете импортируют что-то вроде flask_login или plotly. В Read-the-Docs вы должны увидеть предупреждающие сообщения на этот счет, если вы посмотрите на расширенный журнал (не базовый, который вы опубликовали), доступ к которому можно получить, щелкнув View raw на вкладке Builds. Это предупреждения, а не ошибки. Итак, сборка проходит, но строки документации отсутствуют.

Добавление дополнительных зависимостей замедлит сборку документации, потому что все они должны быть установлены до того, как Sphinx начнет работать. Так что лучшая стратегия — издеваться над ними. Вы также можете проверить это локально.

Пакеты, которые импортируются как import numpy, можно имитировать, добавив параметр Autodoc autodoc_mock_imports на conf.py:

autodoc_mock_imports = ['numpy']

Если вы импортируете объекты непосредственно из пространства имен пакета, например from numpy import array, может потребоваться использование MagicMock из модуля unittest вместо этого:

from unittest.mock import MagicMock
sys.modules['numpy'] = MagicMock()
person John Hennig    schedule 11.05.2021
comment
Спасибо за этот очень четкий и полный ответ, теперь это имеет смысл, и исправление сработало! - person clematologie; 11.05.2021

arrow_upward
0
arrow_downward

Возможно, вам нужно расширить путь к источникам в файле conf.py.

Например, так (если ваш документ находится в подкаталоге):

sys.path.insert(0, os.path.abspath("../"))

вам будет легче помочь, если вы добавите свой conf.py

person djangoliv    schedule 11.05.2021
comment
У меня уже есть подобная (я думаю) строка в моем conf.py или мне нужна другая строка кода, в зависимости от того, читаю ли я документ? ``` import os import sys src_path = os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(file)))) src_path = os.path .normcase(f'{src_path}') sys.path.insert(0, src_path) ``` - person clematologie; 11.05.2021
comment
можно попробовать с абсолютным путем? sys.path.insert(0, os.path.abspath(src_path)). Итак, ваш подкаталог doc похож на dir/dir/dir/doc ? - person djangoliv; 11.05.2021