पायथन स्फिंक्स ऑटोडोक रीडथेड्स पर प्रतिपादन नहीं करता है

Dec 29 2020

मेरे पास Github पर एक पायथन पैकेज है, जिसे spike2py कहा जाता है । मैंने Sphinx और .rst फ़ाइलों का उपयोग करके अपने डॉक्स तैयार किए हैं। इन फ़ाइलों को यहाँ GitHub पर होस्ट किया गया है । मैं make htmlस्थानीय रूप से सफलतापूर्वक चलाने और वांछित आउटपुट प्राप्त करने में सक्षम हूं । यह है कि, दस्तावेज के संदर्भ गाइड भाग API स्वचालित रूप से docstring मैं अपने कोड में शामिल किया उपयोग करते हुए उत्पन्न, और कॉल का उपयोग करने के लिए संदर्भित शामिल autoclassऔर autofunction( reference_guide.rst )।

उदाहरण के लिए, यहाँ संदर्भ गाइड का पहला भाग कैसा दिखता है, जब मैं इसे स्थानीय रूप से प्रस्तुत करता हूँ:

हालाँकि, जब दस्तावेज़ीकरण प्रदान किया गया है readthedocs( यहाँ देखें ), संदर्भ गाइड में निकाले गए सिद्धांत शामिल नहीं हैं; सिर्फ हेडर .rst फ़ाइल में पाए जाते हैं।

अपेक्षित व्यवहार

मुझे उम्मीद थी कि स्थानीय स्तर पर प्रस्तुत किए जाने वाले रीडथेड्स पर दिए गए डॉक्स समान होंगे। हालांकि, ऐसा नहीं हो रहा है।

यहाँ देखकर , मैंने पुष्टि की है कि संस्करण मेरे प्रलेखन के वर्तमान संस्करण में रीडथेड पर प्रस्तुत किया जा रहा है।

लेकिन जब मैं प्रलेखन के पीडीएफ या एचटीएमएल संस्करणों को डाउनलोड करने का प्रयास करता हूं, तो संदर्भ गाइड में डॉकस्ट्रिंग्स शामिल नहीं है।

अन्य सूचना

रीडथेड्स प्रलेखन के अनुसार , स्थानीय बिल्ड को गिटहब को धक्का नहीं दिया जाना चाहिए; केवल स्रोत फ़ाइलें।

यह कुछ हद तक इस मुद्दे से संबंधित है , लेकिन मैं प्रस्तावित समाधान कार्य करने में सक्षम नहीं था।

अद्यतन मैंने स्टीव पियर्स द्वारा सुझाए गए समाधान का पालन किया और इस समस्या का हल भाग। मैंने एक docs/requirements.txtफ़ाइल के साथ-साथ एक .readthedocs.ymlफ़ाइल भी जोड़ी ।

आगे मैंने देखा कि निर्माण पायथन 3.7.9 का उपयोग कर रहा था। यह देखते हुए कि मैं पायथन> = 3.8 से टाइप संकेत का उपयोग कर रहा था, मुझे .readthedocs.ymlफ़ाइल में पायथन के संस्करण को निर्दिष्ट करना पड़ा ।

तब मैं RTD बिल्ड से यह कहते हुए अटक गया था कि यह मेरी 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

लेकिन मैंने अपने में निम्नलिखित निर्दिष्ट करके इसे हल किया .readthedocs.yml:

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

इस फिक्स के बाद, डॉक्स बिना किसी त्रुटि के दिखाई देते हैं और निम्न शामिल होते हैं:

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

और हाँ, आरटीडी पर सिद्धांत दिखाई दिए।

जवाब

1 StevePiercy Dec 30 2020 at 17:08

आपकी परियोजना की निर्भरता RTD पर निर्दिष्ट नहीं है, लेकिन आपने स्थानीय रूप से निर्भरताएं स्थापित की हैं। आप इसे बिल्ड लॉग में सत्यापित कर सकते हैं । अपने प्रोजेक्ट के बिल्ड पर जाएं, बिल्ड पर क्लिक करें और "कच्चे देखें" पर क्लिक करें।

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)

स्थिति को मापने के लिए, आपको यह निर्दिष्ट करना होगा कि आपकी परियोजना की निर्भरताएं स्थापित की जानी चाहिए। निर्दिष्ट निर्भरताएँ देखें ।

आपको या तो होना चाहिए:

  1. एक पाइप आवश्यकताएँ फ़ाइल बनाएँ जो आवश्यकताओं को निर्दिष्ट करती है , या
  2. एक फ़ाइल बनाएं pip installजो एक विकल्प निर्दिष्ट करता है जो आवश्यकताओं को स्थापित करेगा जो पहले से ही कहीं और परिभाषित हैं, जैसे कि एक setup.py docs_requiresश्लोक में। पिरामिड रिपॉजिटरी में इसके rtd.txt और 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},

एक तो आपने इस फ़ाइल में अपनी परियोजना आवश्यकताओं को परिभाषित किया है, फिर आपको निर्भरता स्थापित करने के लिए इस फ़ाइल को पहचानने के लिए डॉक्स को कॉन्फ़िगर करना होगा। पसंदीदा तरीका कॉन्फ़िगरेशन फ़ाइल का उपयोग करना है , लेकिन आप प्रोजेक्ट के व्यवस्थापक डैशबोर्ड के माध्यम से भी ऐसा कर सकते हैं ।

SoleG Jan 01 2021 at 20:54

मेरे साथ भी ठीक यही समस्या आई. Readthedocs मेरे प्रोजेक्ट से डॉकस्ट्रिंग्स नहीं निकाल सकता क्योंकि इसमें मेरा प्रोजेक्ट मॉड्यूल नहीं मिला।

मैंने इसे डॉक्स / conf.py में 2 सापेक्ष पथ जोड़कर हल किया है:

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

ताकि अब डॉक्स / conf.py के शीर्ष इस प्रकार है:

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