Autodoc Python Sphinx nie renderuje się na readthedoc

Dec 29 2020

Mam pakiet Pythona hostowany na Github o nazwie spike2py . Dokumenty przygotowałem przy użyciu plików Sphinx i .rst. Te pliki są hostowane na GitHub tutaj . Jestem w stanie z powodzeniem działać make htmllokalnie i uzyskać pożądane wyniki. Oznacza to, że część dokumentacji zawierająca przewodnik referencyjny zawiera interfejs API wygenerowany automatycznie przy użyciu łańcucha dokumentacyjnego, który zawarłem w kodzie, i do którego odwołuje się za pomocą wywołań autoclassi autofunction( reference_guide.rst ).

Na przykład, oto jak wygląda pierwsza część Przewodnika po renderowaniu lokalnie:

Jednak gdy dokumentacja jest renderowana readthedocs( patrz tutaj ), przewodnik referencyjny nie zawiera wyodrębnionych dokumentów; tylko nagłówki znalezione w pliku .rst.

Oczekiwane zachowanie

Spodziewałem się, że dokumenty renderowane w readthedoc będą takie same, jak te renderowane lokalnie. Jednak tak się nie dzieje.

Patrząc tutaj , I potwierdziły, że wersja prezentowane na readthedocs w aktualnej wersji mojej dokumentacji.

Ale kiedy próbuję pobrać dokumentację w formacie PDF lub HTML, Przewodnik informacyjny nie zawiera dokumentacji.

Inne informacje

Zgodnie z dokumentacją readthedocs , lokalne kompilacje nie powinny być wypychane do GitHub; tylko pliki źródłowe.

Jest to w pewnym stopniu związane z tą kwestią , ale nie udało mi się sprawić, aby proponowane rozwiązanie zadziałało.

AKTUALIZACJA Zastosowałem rozwiązanie zalecane przez Steve'a Piercy'ego i to rozwiązało część problemu. Dodałem docs/requirements.txtplik, a także .readthedocs.ymlplik.

Następnie zauważyłem, że kompilacja korzystała z Pythona 3.7.9. Biorąc pod uwagę, że korzystałem z podpowiedzi typu z Pythona> = 3.8, musiałem określić wersję Pythona w .readthedocs.ymlpliku.

Potem utknąłem z kompilacją RTD, mówiąc mi, że nie może znaleźć mojego pliku index.rst.

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app.build(args.force_all, filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/application.py", line 348, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 297, in build_update
    self.build(to_build,
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 311, in build
    updated_docnames = set(self.read())
  File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 421, in read
    raise SphinxError('master file %s not found' %
sphinx.errors.SphinxError: master file /home/docs/checkouts/readthedocs.org/user_builds/spike2py/checkouts/latest/docs/index.rst not found

Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/spike2py/checkouts/latest/docs/index.rst not found

Ale potem rozwiązałem to, podając następujące informacje w moim .readthedocs.yml:

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

Po tej poprawce dokumenty są tworzone przy użyciu czegoś, co wygląda na to, że nie zawiera błędów i zawiera następujące elementy:

generating indices...  genindex py-modindexdone
highlighting module code... [ 20%] spike2py.channels
highlighting module code... [ 40%] spike2py.plot
highlighting module code... [ 60%] spike2py.read
highlighting module code... [ 80%] spike2py.sig_proc
highlighting module code... [100%] spike2py.trial

I tak, doktryny pojawiły się w RTD.

Odpowiedzi

1 StevePiercy Dec 30 2020 at 17:08

Zależności twojego projektu nie są określone w RTD, ale zależności zostały zainstalowane lokalnie. Możesz to sprawdzić w dzienniku kompilacji . Odwiedź kompilacje swojego projektu, kliknij kompilację i kliknij „wyświetl nieprzetworzone”.

WARNING: autodoc: failed to import class 'trial.TrialInfo' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'trial.Trial' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'trial.load' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.ChannelInfo' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Channel' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Event' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Keyboard' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Waveform' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Wavemark' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'sig_proc.SignalProcessing' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'plot.plot_channel' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'plot.plot_trial' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'read.read' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)

Aby zaradzić tej sytuacji, musisz określić, że należy zainstalować zależności projektu. Zobacz Określanie zależności .

Musisz:

  1. Utwórz plik wymagań pip, który określa wymagania , lub
  2. Utwórz plik określający pip installopcję, która zainstaluje wymagania, które zostały już zdefiniowane w innym miejscu, na przykład w setup.py docs_requiressekcji. Zobacz przykład w repozytorium Pyramid z jego rtd.txt i setup.py .

rtd.txt

-e .[docs]

setup.py

docs_extras = [
    'Sphinx >= 3.0.0',  # Force RTD to use >= 3.0.0
    'docutils',
    'pylons-sphinx-themes >= 1.0.8',  # Ethical Ads
    'pylons_sphinx_latesturl',
    'repoze.sphinx.autointerface',
    'sphinxcontrib-autoprogram',
]
# ...
    extras_require={'testing': testing_extras, 'docs': docs_extras},

Jeśli zdefiniowałeś wymagania projektu w tym pliku, musisz skonfigurować Read the Docs, aby rozpoznawał ten plik i instalował zależności. Preferowaną metodą jest użycie pliku konfiguracyjnego , ale można to również zrobić za pośrednictwem panelu administracyjnego projektu .

SoleG Jan 01 2021 at 20:54

Miałem dokładnie ten sam problem. Readthedocs nie mógł wyodrębnić dokumentów z mojego projektu, ponieważ nie znalazł mojego modułu projektu.

Rozwiązałem to, dodając 2 ścieżki względne w docs / conf.py:

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

Więc teraz górna część docs / conf.py wygląda następująco:

import os
import sys
import sphinx_rtd_theme

    # If extensions (or modules to document with autodoc) are in another directory,
    # add these directories to sys.path here. If the directory is relative to the
    # documentation root, use os.path.abspath to make it absolute, like shown here.
    sys.path.insert(0, os.path.abspath("."))
    sys.path.insert(0, os.path.abspath("../"))
    sys.path.insert(1, os.path.dirname(os.path.abspath("../")) + os.sep + "feature_engine")