Używam Sphinx do dokumentowania projektu innego niż Python. Chcę rozprowadzić ./doc
foldery w każdym submodule_name.rst
module podrzędnym, zawierające pliki dokumentujące ten moduł. Następnie chcę zassać te pliki do głównej hierarchii, aby utworzyć specyfikację dla całego projektu.
To znaczy:
Project
docs
spec
project_spec.rst
conf.py
modules
module1
docs
module1.rst
src
module2
docs
module2.rst
src
Próbowałem dołączyć pliki do głównego project_spec.rst
dokumentu do drzewa w następujący sposób:
.. toctree::
:numbered:
:maxdepth: 2
Module 1 <../../modules/module1/docs/module1>
Jednak ten komunikat o błędzie powoduje:
OSTRZEŻENIE: toctree zawiera odniesienie do nieistniejącego dokumentu u'modules / module1 / docs / module1 '
Czy ../
w jakiś sposób nie można użyć w ścieżce dokumentu?
Aktualizacja: Dodano lokalizację conf.py
Aktualizacja: Poza poniższą sztuczką zawierającą, jest to nadal (2019) niemożliwe. Istnieje otwarty problem, który jest wciąż popychany do przodu: https://github.com/sphinx-doc/sphinx/issues/701
źródło
.rst
rozszerzenie do liniiModule 1 <../../modules/module1/docs/module1>
?source_suffix
jest to ustawione.rst
w twoimconf.py
pliku konfiguracyjnym. Gdzie jest ten plik w twojej hierarchii katalogów, skoro wydaje się, że wszystkie ścieżki są względne w stosunku do tego pliku?source_suffix
jest ustawiony na.rst
iconf.py
znajduje się w tym samym folderze coproject_spec.rst
plik.Odpowiedzi:
Tak, możesz!
Zamiast łącza symbolicznego (które nie będzie działać w systemie Windows), utwórz dokument zastępczy, który nie zawiera nic poza
.. include::
dyrektywą.Natknąłem się na to, próbując połączyć się z plikiem README, który znajdował się w górnej części drzewa źródłowego. W pliku o nazwie
readme_link.rst
:Następnie
index.rst
sprawiłem, że drzewo do toctree wygląda następująco:Contents: .. toctree:: :maxdepth: 2 readme_link other_stuff
Teraz mam link do moich informacji o wydaniu na mojej stronie indeksu.
Podziękowania dla http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html za sugestię
źródło
docs
), Który prowadzi do bieżącego- katalogu („.”). Następnie możesz użyć: download:docs\foo.rst
i to zadziała dla plików wdocs
folderze lub w folderze nadrzędnym... include:: ../readme.rst
tym rozszerzenia.Wygląda na to, że odpowiedź brzmi nie, dokumenty wymienione w drzewie toc muszą znajdować się w katalogu źródłowym , czyli katalogu zawierającym dokument główny i
conf.py
(i wszelkie podkatalogi).Z listy mailingowej sphinx-dev :
Więc zamiast kopiować pliki za pomocą,
shutil
możesz spróbować dodać dowiązania symboliczne do wszystkich modułów wProject/docs/spec
katalogu. Jeśli utworzysz dowiązanie symboliczne doProject/modules
siebie, będziesz odnosić się do tych plików w swoim drzewie zadań po prostu tak, jakmodules/module1/docs/module1
itd.źródło
sys.path
pliku conf.py, ale to nie zadziałało.W conf.py dodaj względne ścieżki do systemu za pomocą sys.path i os.path
Na przykład:
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'))
Następnie użyj swojego index.rst jak zwykle, odwołując się do pierwszych plików w tym samym katalogu. Więc w moim index.rst w moim lokalnym folderze Sphinx:
Contents: .. toctree:: :maxdepth: 4 Package1 <package1.rst> Package2 <package2.rst> Package3 <package3.rst>
Następnie w package1.rst powinieneś być w stanie normalnie odwołać się do pakietów względnych.
źródło
Package1
? Czy jest to najpierwpath
określone przy użyciusys.path.insert
? A może jest gdzieś samouczek? Nie mogę znaleźć odpowiedniego doktora.Package1
jest nazwaną pozycją, więc w spisie treści jako tytuł sekcji wyświetlany jest tekst „Pakiet1”.Możliwe jest również skonfigurowanie sfinksa tak, aby miał tylko plik index.rst w katalogu głównym i wszystkie inne rzeczy sfinksa w Project / docs:
W systemie Windows przeniosłem wszystkie pliki sfinks i katalogi (z wyjątkiem index.rst) do docs / i zmieniłem:
docs/make.bat
: Zmianado
docs/conf.py
: Dodajsys.path.insert(0, os.path.abspath('..'))
źródło
Rozwiązałem dość podobny problem z tą różnicą, że chciałem dołączyć zewnętrzny notatnik jupyter. Zainstalowałem nbsphinx, ale nie mogłem go uruchomić. Co nie działa:
Miałem katalog, w którym chciałem umieścić katalog główny w ścieżce:
conf.py:
import os import sys sys.path.insert(...
Korzystanie z
.. include:: directive
pliku było zawarte w dokumentacji, ale tak jak jest.Ostatecznie tym, co rozwiązało problem, była instalacja pakietu nbsphinx-link
źródło
Jednym z rozwiązań, jeśli naprawdę niemożliwe jest użycie odnośników względnych, które tworzą kopię zapasową
../
, można użyćshutil
do skopiowania plików do drzewa folderów specyfikacji wconf.py
specyfikacji, ale wolałbym nie mieć wielu kopii, chyba że jest to absolutnie konieczne.źródło