Tự động mã hóa Python Sphinx không hiển thị trên readthedocs

Question

Tôi có một gói Python được lưu trữ trên Github có tên là spike2py . Tôi đã chuẩn bị tài liệu của mình bằng cách sử dụng các tệp Sphinx và .rst. Các tệp này được lưu trữ trên GitHub tại đây . Tôi có thể chạy thành công make htmlcục bộ và có được đầu ra mong muốn. Đó là, phần Hướng dẫn Tham khảo của tài liệu chứa API được tạo tự động bằng cách sử dụng chuỗi doc mà tôi đã đưa vào mã của mình và được tham chiếu bằng cách sử dụng các lệnh gọi đến autoclassvà autofunction( reference_guide.rst ).

Ví dụ: đây là phần đầu tiên của Hướng dẫn Tham khảo trông như thế nào khi tôi kết xuất nó cục bộ:

Tuy nhiên, khi tài liệu được hiển thị trên readthedocs( xem tại đây ), Hướng dẫn Tham khảo không chứa các tài liệu được trích xuất; chỉ là các tiêu đề được tìm thấy trong tệp .rst.

Hành vi mong đợi

Tôi mong đợi các tài liệu được hiển thị trên readthedocs giống với những tài liệu được hiển thị cục bộ. Tuy nhiên, điều này không xảy ra.

Bằng cách nhìn vào đây , tôi đã xác nhận rằng phiên bản đang được trình bày trên readthedocs trong phiên bản hiện tại của tài liệu của tôi.

Nhưng khi tôi cố gắng tải xuống các phiên bản PDF hoặc HTML của tài liệu, thì Hướng dẫn Tham khảo không bao gồm docstrings.

Thông tin khác

Theo tài liệu readthedocs , không nên đẩy các bản dựng cục bộ lên GitHub; chỉ các tệp nguồn.

Điều này có phần liên quan đến vấn đề này , nhưng tôi không thể làm cho giải pháp được đề xuất hoạt động.

CẬP NHẬT Tôi đã làm theo giải pháp do Steve Piercy đề xuất và giải pháp này đã giải quyết được một phần của vấn đề. Tôi đã thêm một docs/requirements.txttệp cũng như một .readthedocs.ymltệp.

Tiếp theo, tôi nhận thấy rằng bản dựng đang sử dụng Python 3.7.9. Cho rằng tôi đang sử dụng gợi ý kiểu từ Python> = 3.8, tôi phải chỉ định phiên bản Python trong .readthedocs.ymltệp.

Sau đó, tôi bị mắc kẹt với bản dựng RTD nói với tôi rằng nó không thể tìm thấy tệp index.rst của tôi.

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

Nhưng sau đó tôi đã giải quyết điều này bằng cách chỉ định những điều sau đây trong của tôi .readthedocs.yml:

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

Sau bản sửa lỗi này, tài liệu được tạo với những gì dường như không có lỗi và bao gồm những điều sau:

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

Và vâng, các học thuyết đã xuất hiện trên RTD.

Answer 1

Các phụ thuộc dự án của bạn không được chỉ định trên RTD, nhưng bạn đã cài đặt các phụ thuộc cục bộ. Bạn có thể xác minh điều này trong nhật ký xây dựng . Truy cập Công trình xây dựng của dự án của bạn, nhấp vào một công trình và nhấp vào "xem thô".

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)

Để khắc phục tình trạng này, bạn phải chỉ định rằng các phụ thuộc dự án của bạn phải được cài đặt. Xem Chỉ định phụ thuộc .

Bạn phải:

1. Tạo một tệp yêu cầu pip chỉ định các yêu cầu hoặc
2. Tạo một tệp chỉ định một pip installtùy chọn sẽ cài đặt các yêu cầu đã được xác định ở nơi khác, chẳng hạn như trong một khổ setup.py docs_requiresthơ. Xem ví dụ trong kho lưu trữ Kim tự tháp với rtd.txt và 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},

Một bạn đã xác định các yêu cầu dự án của mình trong tệp này, sau đó bạn phải định cấu hình Đọc tài liệu để nhận dạng tệp này để cài đặt các phần phụ thuộc. Phương pháp ưa thích là sử dụng tệp cấu hình , nhưng bạn cũng có thể thực hiện việc này thông qua Bảng điều khiển dành cho quản trị viên của dự án .

Answer 2

Tôi đã có cùng vấn đề y hệt. Readthedocs không thể trích xuất docstrings từ Dự án của tôi vì nó không tìm thấy mô-đun dự án của tôi.

Tôi đã giải quyết vấn đề này bằng cách thêm 2 đường dẫn tương đối trong docs / conf.py:

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

Vì vậy, bây giờ phần trên cùng của docs / conf.py trông như sau:

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")