क्या स्फिंक्स उन दस्तावेज़ों से लिंक कर सकता है जो रूट दस्तावेज़ के नीचे निर्देशिका में स्थित नहीं हैं?

Question

मैं एक गैर-पायथन परियोजना के दस्तावेज के लिए स्फिंक्स का उपयोग कर रहा हूं। मैं उस मॉड्यूल को दस्तावेज़ करने के लिए फ़ाइलों ./docवाले प्रत्येक सबमॉड्यूल में फ़ोल्डर वितरित करना चाहता हूं submodule_name.rst। मैं तो पूरी डिजाइन के लिए एक युक्ति बनाने के लिए उन फ़ाइलों को मास्टर पदानुक्रम में चूसना चाहता हूं।

अर्थात:

Project
  docs
    spec
      project_spec.rst
      conf.py
  modules
    module1
      docs
        module1.rst
      src
    module2
      docs
        module2.rst
      src

मैंने मास्टर project_spec.rstडॉक्यूमेंट में फाइल को इस तरह शामिल करने का प्रयास किया :

.. toctree::
   :numbered:
   :maxdepth: 2

   Module 1 <../../modules/module1/docs/module1>

हालाँकि यह त्रुटि संदेश परिणाम:

चेतावनी: toctree में कोई भी दस्तावेज़ u'modules / मॉड्यूल 1 / डॉक्स / मॉड्यूल 1 'का संदर्भ नहीं है

क्या ../किसी तरह से दस्तावेज़ पथ में उपयोग करना संभव नहीं है ?

अपडेट: कन्फ़्यूज़्ड स्थान जोड़ा गया

अद्यतन: नीचे शामिल चाल के अलावा, यह अभी भी (2019) संभव नहीं है। एक खुला मुद्दा है जो आगे बढ़ता रहता है: https://github.com/sphinx-doc/sphinx/sues/701

Comments

क्या आपको .rstलाइन में एक्सटेंशन जोड़ने की आवश्यकता है Module 1 <../../modules/module1/docs/module1>?

— क्रिस

मुझे ऐसा नहीं लगता क्योंकि स्फिंक्स डॉक्स में : चूंकि रेस्ट सोर्स फाइल्स में अलग-अलग एक्सटेंशन हो सकते हैं (कुछ लोग जैसे .txt, कुछ लाइक .rst - एक्सटेंशन को source_suffix से कॉन्फ़िगर किया जा सकता है) और अलग-अलग OS में अलग-अलग सेपरेटर होते हैं, Sphinx। उन्हें सार: सभी "दस्तावेज़ नाम" स्रोत निर्देशिका के सापेक्ष हैं, एक्सटेंशन छीन लिया गया है, और पथ विभाजक स्लैश में परिवर्तित हो गए हैं।

— mc_electron

ठीक है, बस एक अनुमान! तो मुझे लगता है कि आपके कॉन्फ़िगरेशन फ़ाइल में source_suffixसेट है । इसके अलावा, आपकी निर्देशिका पदानुक्रम में यह फ़ाइल कहां है, क्योंकि ऐसा लगता है कि सभी पथ इस फ़ाइल के सापेक्ष हैं? .rstconf.py

— क्रिस

हां, फ़ाइल के समान फ़ोल्डर में source_suffixसेट है .rstऔर conf.pyहै project_spec.rst।

— mc_electron

Answer 1

हाँ तुम कर सकते हो!

सिम्लिंक के बदले (जो विंडोज पर काम नहीं करेगा), एक स्टब डॉक्यूमेंट बनाएं, जिसमें एक .. include::निर्देश के अलावा कुछ भी न हो ।

मैं इस में भाग लेने के लिए कोशिश कर रहा था एक README फ़ाइल है कि स्रोत पेड़ के शीर्ष में था। मैंने निम्नलिखित को एक फ़ाइल में रखा है readme_link.rst:

.. include:: ../README

फिर index.rst, मैंने इनक्ट्री की तरह बनाया:

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

और अब मेरे पास मेरे इंडेक्स पेज पर मेरे जारी किए गए नोट्स का लिंक है।

सुझाव के लिए http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html धन्यवाद

Comments

यह README की छवियां या समान हैं जिनके सापेक्ष पथ हैं जो निर्देशिका index.rst के भीतर मान्य नहीं हैं, आप इसे कैसे संभालते हैं? मुझे 'छवि फ़ाइल पठनीय नहीं है' त्रुटियां हैं।

— लुकास डब्ल्यू

हाँ, आप यह भी कर सकते हैं कि यूनिक्स में सहानुभूति के साथ। आप डॉक्स-फ़ोल्डर (यानी docs) के समान नाम के साथ एक लिंक बना सकते हैं जो वर्तमान-डीआईआर ('') से लिंक करता है। तब आप उपयोग कर सकते हैं: डाउनलोड करें: docs\foo.rstऔर यह docsफ़ोल्डर को फाइल करने या माता-पिता के लिए काम करेगा ।

— एकॉस्टिस

मैं बस यहाँ वापस आया और इस जवाब को स्वीकार किया, धन्यवाद! छवियों के बारे में निश्चित नहीं है, लेकिन आप उन्हें हमेशा conf.py में कॉपी कर सकते हैं।

— mc_electron

मुझे .. include:: ../readme.rstएक्सटेंशन सहित उपयोग करने की आवश्यकता थी ।

— नू एवरेस्ट

README.rst के केवल भाग को शामिल करने के लिए: muffinresearch.co.uk/…

— ederag

Answer 2

ऐसा लगता है कि उत्तर नहीं है, टो-ट्री में सूचीबद्ध दस्तावेज़ों को स्रोत निर्देशिका के भीतर रहना चाहिए , यानी निर्देशिका, जिसमें आपके मास्टर दस्तावेज़ और conf.py(और कोई उपनिर्देशिका) हों।

से स्फिंक्स-देव मेलिंग सूची :

STScI पर, हम Sphinx में व्यक्तिगत परियोजनाओं के लिए दस्तावेज लिखते हैं, और फिर एक "मास्टर दस्तावेज़" भी बनाते हैं जिसमें इन अन्य परियोजना-विशिष्ट दस्तावेज़ों के एक नंबर (toctree का उपयोग करना) शामिल हैं। ऐसा करने के लिए, हम मास्टर दस्तावेज़ के डॉक सोर्स डायरेक्टरी में प्रोजेक्ट्स के डॉक सोर्स डाइरेक्ट्रीज़ में सहानुभूति पैदा करते हैं, क्योंकि टॉकट्री वास्तव में डॉक सोर्स ट्री के बाहर की फाइलों को शामिल करना नहीं चाहती है।

इसलिए फ़ाइलों का उपयोग करने के बजाय shutilआप Project/docs/specनिर्देशिका में अपने सभी मॉड्यूलों के लिए सहानुभूति जोड़ने का प्रयास कर सकते हैं । यदि आप अपने लिए एक सिमलिंक बनाते हैं, Project/modulesतो इन फ़ाइलों को अपने टो-ट्री में बस के रूप में संदर्भित करें modules/module1/docs/module1आदि।

Comments

यह बहुत बुरा है। Word डॉक्स से Sphinx पर स्विच करने की कोशिश में मेरे द्वारा देखे गए फायदों में से एक यह है कि आप अपनी परियोजना में एक पुन: प्रयोज्य हार्डवेयर मॉड्यूल को आयात कर सकते हैं और डिजाइन के लिए मास्टर प्रलेखन में इसे शामिल कर सकते हैं। मैं सिमिलिंक का उपयोग करूंगा लेकिन अफसोस मैं खिड़कियों पर हूं।

— mc_electron

sys.pathपोस्टरिटी के लिए, मैंने सबमॉड्यूल डॉक फोल्डर को कन्फैक्शन में जोड़ने की कोशिश की, लेकिन वह काम नहीं आया।

— mc_electron

@mc_electron विंडोज पर सिमिलिंक के लिए, mklink कमांड का उपयोग करें।

— जेरेमी

Answer 3

Conf.py में, sys.path और os.path का उपयोग करके सिस्टम में सापेक्ष पथ जोड़ें

उदाहरण के लिए:

import os
import sys

sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../../Directory1'))
sys.path.insert(0, os.path.abspath('../../Directory2'))

फिर समान निर्देशिका में rst फ़ाइलों को संदर्भित करते हुए, हमेशा की तरह अपने index.rst का उपयोग करें। इसलिए अपने स्थानीय Sphinx फ़ोल्डर में मेरे index.rst में:

Contents:

.. toctree::
   :maxdepth: 4

   Package1 <package1.rst>
   Package2 <package2.rst>
   Package3 <package3.rst>

तब package1.rst में, आपको सामान्य रूप से सापेक्ष पैकेजों को संदर्भित करने में सक्षम होना चाहिए।

Package1 package
=====================

Submodules
----------

Submodule1 module
----------------------------------

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

Submodule1 module
----------------------------------

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

Comments

क्या यह नया व्यवहार है? इसे किस संस्करण में जोड़ा गया था?

— mc_electron

आगे महान शुरुआत करने वालों को सूचित करने के लिए महान होगा। उदाहरण के लिए, क्या है Package1? यह पहली बार pathउपयोग करने के लिए निर्दिष्ट है sys.path.insert? या, कहीं एक ट्यूटोरियल है? मैं संबंधित डॉक नहीं खोज सकता।

— मानवलन गजपति

Package1एक नामित प्रविष्टि है जिससे कि TOC अनुभाग के शीर्षक के रूप में "Package1" दिखाता है।

— पाब्लो

यह आपको किसी अन्य निर्देशिका में पायथन मॉड्यूल को ऑटोडोक करने की अनुमति देता है, लेकिन यह आपको किसी अन्य निर्देशिका में आरएसटी फ़ाइलों को शामिल करने की अनुमति नहीं देता है।

— mc_electron

Answer 4

यह भी संभव है कि स्फिंक्स को कॉन्फ़िगर करने के लिए रूट में केवल index.rst फ़ाइल और प्रोजेक्ट / डॉक्स में अन्य सभी स्फिंक्स सामान हों:

खिड़कियों के लिए मैंने डॉक्स / और बदले में सभी स्फिंक्स फ़ाइलों और डायरियों (index.rst को छोड़कर) को स्थानांतरित किया:

docs/make.bat: परिवर्तन

set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS%  .

सेवा

set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS%  -c . ..

docs/conf.py: जोड़ें

sys.path.insert(0, os.path.abspath('..'))

Comments

धन्यवाद! एक ही दस्तावेज़ से संदर्भित एक रिपॉजिटरी में कई संबंधित पैकेज होने पर यह कॉन्फ़िगरेशन मेरे लिए ठीक काम करता है।

— ग्रेगोर म्यूलिगर

Answer 5

मैंने अपनी समान समस्या का समाधान उस अंतर के साथ किया, जिसमें मैं बाहरी ज्यूपिटर नोटबुक को शामिल करना चाहता था। मैंने nbsphinx स्थापित किया था, लेकिन मैं इसे काम नहीं कर सका। क्या काम नहीं किया:

1. मेरे पास वह निर्देशिका थी जिसे मैं रूट में शामिल करना चाहता था:

   conf.py:

   import os import sys sys.path.insert(...

2. .. include:: directiveफ़ाइल का उपयोग करना प्रलेखन में शामिल किया गया था लेकिन जैसा है।

अंत में जो समस्या हल हुई वह पैकेज nbsphinx-link स्थापित करना था

Answer 6

एक समाधान, अगर यह वास्तव में असंभव है कि रिश्तेदार लिंक का उपयोग करें जो ../कि मैं shutilकल्पना के लिए कल्पना फ़ोल्डर के पेड़ में फ़ाइलों की प्रतिलिपि बनाने के लिए उपयोग कर सकता हूं conf.py, लेकिन जब तक बिल्कुल आवश्यक न हो, तब तक मेरे पास कई प्रतियां नहीं होंगी।