Ik gebruik Sphinx om een niet-Python-project te documenteren. Ik wil ./docmappen distribueren in elke submodule, met daarin submodule_name.rstbestanden om die module te documenteren. Ik wil die bestanden vervolgens in de hoofdhiërarchie zuigen om een specificatie voor het hele ontwerp te maken.
D.w.z.:
Project
docs
spec
project_spec.rst
conf.py
modules
module1
docs
module1.rst
src
module2
docs
module2.rst
src
Ik heb geprobeerd om bestanden als volgt in het hoofddocument project_spec.rstop te nemen:
.. toctree::
:numbered:
:maxdepth: 2
Module 1 <../../modules/module1/docs/module1>
Dit foutbericht resulteert echter in:
WAARSCHUWING: toctree bevat verwijzing naar niet-bestaand document u’modules/module1/docs/module1′
Is het op de een of andere manier niet mogelijk om ../in een documentpad te gebruiken?
Update: Conf.py-locatie toegevoegd
Bijwerken:
Afgezien van de onderstaande include-truc is dit nog steeds (2019) niet mogelijk. Er is een openstaande kwestie die steeds verder naar voren wordt geschoven: https://github.com/sphinx- doc/sphinx/issues/701
Antwoord 1, autoriteit 100%
Ja, dat kan!
In plaats van een symbolische link (die niet werkt op Windows), maak je een stub-document dat niets anders bevat dan een .. include::-instructie.
Ik kwam dit tegen toen ik probeerde te linken naar een README-bestand dat zich bovenaan de bronstructuur bevond. Ik heb het volgende in een bestand met de naam readme_link.rstgezet:
.. include:: ../README
Vervolgens maakte ik in index.rstde toctree als volgt:
Contents:
.. toctree::
:maxdepth: 2
readme_link
other_stuff
En nu heb ik een link naar mijn release-opmerkingen op mijn indexpagina.
Met dank aan http://reinout.vanrees.org/weblog /2010/12/08/include-external-in-sphinx.htmlvoor de suggestie
Antwoord 2, autoriteit 10%
Het lijkt erop dat het antwoord nee is, de documenten in de toc-tree moeten zich in de bronmap, dat wil zeggen de map met uw master documenten conf.py(en eventuele submappen).
Van de sphinx-dev mailinglijst:
Bij STScI schrijven we documentatie voor individuele projecten in Sphinx, en produceren dan ook een “masterdocument” dat (met behulp van toctree) een aantal van deze andere projectspecifieke documenten bevat. Om dit te doen, creëren we symbolische links in de doc-bronmap van het hoofddocument naar de doc-bronmappen van de projecten, aangezien toctree echt geen bestanden buiten de doc-bronstructuur lijkt te willen opnemen.
Dus in plaats van bestanden te kopiëren met behulp van shutilkunt u proberen symbolische links toe te voegen aan al uw modules in de Project/docs/specdirectory. Als je een symbolische link naar Project/modulesmaakt, zou je deze bestanden in je toc-tree eenvoudigweg als modules/module1/docs/module1etc.
Antwoord 3, autoriteit 8%
Voeg in conf.py de relatieve paden toe aan het systeem met sys.path en os.path
Bijvoorbeeld:
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'))
Gebruik vervolgens uw index.rst zoals gewoonlijk, verwijzend naar de eerste bestanden in dezelfde map. Dus in mijn index.rst in mijn lokale Sphinx-map:
Contents:
.. toctree::
:maxdepth: 4
Package1 <package1.rst>
Package2 <package2.rst>
Package3 <package3.rst>
Dan zou je in package1.rst in staat moeten zijn om normaal naar de relatieve pakketten te verwijzen.
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:
Antwoord 4, autoriteit 2%
Ik heb mijn vrij gelijkaardige probleem opgelost met het verschil dat ik een externe jupyter-notebook wilde toevoegen. Ik had nbsphinx geïnstalleerd, maar ik kreeg het niet werkend.
Wat werkte niet:
-
Ik had de map waarin ik de root in het pad wilde opnemen:
conf.py :
import os
import sys
sys.path.insert(... -
Met behulp van de
.. include:: directivewas het bestand opgenomen in de documentatie, maar zoals het is.
Eindelijk wat opgelosthet probleem was het installeren van pakket nbsphinx-link
Antwoord 5
Het is ook mogelijk om sphinx te configureren om alleen het index.rst-bestand in de root te hebben en alle andere sphinx-dingen in Project/docs:
Voor Windows heb ik alle sphinx-bestanden en mappen (behalve index.rst) naar docs/ verplaatst en gewijzigd:
docs/make.bat: Wijzigen
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
naar
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% -c . ..
docs/conf.py: toevoegen
sys.path.insert(0, os.path.abspath('..'))
Antwoord 6
Een alternatieve techniek waarvoor geen stub-bestanden hoeven te worden gemaakt, is het gebruik van absolute verwijzingen(beginnend met /) binnen je toctree root, en de bronmap instellen op de laagste gemeenschappelijke voorouder bij het aanroepen van sphinx-build. Voorbeeld directory layout:
/path/to/common/ancestor
├── a
│ └── foo.rst
├── b
│ ├── bar.rst
│ ├── x
│ │ └── index.rst
│ └── y
│ └── boz.rst
└── c
└── baz.rst
En b/x/index.rst:
.. toctree::
/a/foo
/b/bar
/b/y/boz
/c/baz
En uw sphinx-build-opdracht kan er als volgt uitzien:
sphinx-build -c <confdir> -b html -D masterdoc=b/x/index /path/to/common/ancestor <outdir>
Ik heb dit getest met sphinx 3.0.2.
Antwoord 7
Mijn antwoord is in wezen de @Dan Menes, maar dan voor Myst-parser in plaats van opnieuw gestructureerd.
Ik zou dit het liefst als commentaar toevoegen aan het antwoord van @Dan Menes omdat het daar thuishoort, maar opmerkingen laten me niet toe om de opmaak te doen, de Myst-syntaxis is gevoelig voor nieuwe regels en de opmerkingen zijn beperkt in tekens. Dus ik post het als een apart antwoord, zelfs als het gerelateerd is aan een bestaand antwoord.
Als u de Myst wilt opnemen, moet u deze iets anders opmaken:
```{include} ../main/post_installation_windows.md
```
Het kan zichzelf inpakken om ook de herstructureerde opmaak uit te voeren (het opgenomen bestand wordt dan behandeld zoals het is geschreven in geherstructureerd):
```{eval-rst}
.. include:: snippets/include-rst.rst
```
Het gebruik van de oorspronkelijke Myst-syntaxis is echter eenvoudiger. En het heeft betere functies, bijvoorbeeld, alleen het opnemen van het bestand lost geen enkele verwijzing in het opgenomen bestand correct op, terwijl include-literal zou moeten:
```{include-literal} ../../example.md
:language: md
```
Zoals je zou kunnen ontdekken dat het opnemen van een eenvoudig document oké is, maar dat het toevoegen van een complex document met veel verwijzingen meer kopzorgen zal veroorzaken, zou ik de experimentele include-literal(vanaf versie 0.12. 7)
Referentie:
https://myst-parser.readthedocs.io/en/latest/ gebruik/howto.html
Antwoord 8
Een oplossing, als het echt onmogelijk is om relatieve links te gebruiken die een back-up maken van ../, is dat ik shutilkan gebruiken om de bestanden te kopiëren naar de spec mappenboom in de conf.pyvoor de specificatie, maar ik heb liever niet meerdere exemplaren tenzij absoluut noodzakelijk.