Czy sphinx może tworzyć linki do dokumentów, które nie znajdują się w katalogach poniżej dokumentu głównego?

90

Używam Sphinx do dokumentowania projektu innego niż Python. Chcę rozprowadzić ./docfoldery w każdym submodule_name.rstmodule 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.rstdokumentu 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

mc_electron
źródło
Czy potrzebujesz dodać .rstrozszerzenie do linii Module 1 <../../modules/module1/docs/module1>?
Chris,
Nie sądzę, ponieważ w dokumentach Sphinx : Ponieważ pliki źródłowe reST mogą mieć różne rozszerzenia (niektórzy ludzie, jak .txt, inni, jak .rst - rozszerzenie można skonfigurować za pomocą source_suffix), a różne systemy operacyjne mają różne separatory ścieżek, Sphinx streszcza je: wszystkie „nazwy dokumentów” odnoszą się do katalogu źródłowego, rozszerzenie jest usuwane, a separatory ścieżek są konwertowane na ukośniki.
mc_electron
OK, tylko zgaduję! Zakładam więc, że source_suffixjest to ustawione .rstw twoim conf.pypliku 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?
Chris
Tak, source_suffixjest ustawiony na .rsti conf.pyznajduje się w tym samym folderze co project_spec.rstplik.
mc_electron

Odpowiedzi:

108

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:

.. include:: ../README

Następnie index.rstsprawił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ę

Dan Menes
źródło
5
Jeśli plik README zawiera obrazy lub podobne obrazy, których ścieżki względne są nieprawidłowe w katalogu, w którym znajduje się plik index.rst, jak sobie z tym poradzisz? Otrzymuję błąd „Nie można odczytać pliku obrazu”.
Lucas W
Tak, możesz to również zrobić w Uniksie za pomocą linków symbolicznych. Możesz utworzyć łącze o tej samej nazwie, co folder docs (tj. docs), Który prowadzi do bieżącego- katalogu („.”). Następnie możesz użyć: download: docs\foo.rsti to zadziała dla plików w docsfolderze lub w folderze nadrzędnym.
ankostis
1
Właśnie wróciłem tutaj i zaakceptowałem tę odpowiedź, dzięki! Nie jestem pewien co do obrazów, ale zawsze możesz je skopiować w pliku conf.py.
mc_electron
11
Musiałem użyć, w .. include:: ../readme.rsttym rozszerzenia.
nu everest
1
Aby uwzględnić tylko część README.rst: muffinresearch.co.uk/ ...
ederag
14

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 :

W STScI piszemy dokumentację dla poszczególnych projektów w Sphinx, a następnie tworzymy „dokument główny”, który zawiera (używając toctree) wiele innych dokumentów specyficznych dla projektu. Aby to zrobić, tworzymy dowiązania symboliczne w katalogu źródłowym dokumentu głównego do katalogów źródłowych dokumentów projektów, ponieważ toctree naprawdę nie chce dołączać plików spoza drzewa źródłowego dokumentów.

Więc zamiast kopiować pliki za pomocą, shutilmożesz spróbować dodać dowiązania symboliczne do wszystkich modułów w Project/docs/speckatalogu. Jeśli utworzysz dowiązanie symboliczne do Project/modulessiebie, będziesz odnosić się do tych plików w swoim drzewie zadań po prostu tak, jak modules/module1/docs/module1itd.

Chris
źródło
3
Szkoda. Jedną z zalet, które widzę podczas próby przejścia z dokumentów Word na Sphinx, jest to, że możesz zaimportować do projektu moduł sprzętowy wielokrotnego użytku i po prostu dołączyć jego dokumentację do głównej dokumentacji projektu. Używałbym linków symbolicznych, ale niestety jestem w systemie Windows.
mc_electron
Dla potomności próbowałem dodać folder doc modułu submodułu do sys.pathpliku conf.py, ale to nie zadziałało.
mc_electron
1
@mc_electron W przypadku łączy symbolicznych w systemie Windows użyj polecenia mklink.
Jeremy
11

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.

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:
Kingscote
źródło
Czy to nowe zachowanie? W jakiej wersji został dodany?
mc_electron
2
Byłoby wspaniale, gdyby został dokładniej opisany, aby poinformować początkujących. Na przykład, co to jest Package1? Czy jest to najpierw pathokreślone przy użyciu sys.path.insert? A może jest gdzieś samouczek? Nie mogę znaleźć odpowiedniego doktora.
Manavalan Gajapathy
Package1jest nazwaną pozycją, więc w spisie treści jako tytuł sekcji wyświetlany jest tekst „Pakiet1”.
PabloC
2
Pozwala to na automatyczne kodowanie modułów Pythona w innym katalogu, ale nie pozwala na umieszczanie plików RST w innym katalogu.
mc_electron
1

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: Zmiana

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

do

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

docs/conf.py: Dodaj

sys.path.insert(0, os.path.abspath('..'))
mrtnlrsn
źródło
Dzięki! Ta konfiguracja działa dobrze, gdy mam wiele powiązanych pakietów w jednym repozytorium, do których odwołuje się ta sama dokumentacja.
Gregor Müllegger
1

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:

  1. 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(...

  2. Korzystanie z .. include:: directivepliku było zawarte w dokumentacji, ale tak jak jest.

Ostatecznie tym, co rozwiązało problem, była instalacja pakietu nbsphinx-link

DesperateEngineer
źródło
0

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ć shutildo skopiowania plików do drzewa folderów specyfikacji w conf.pyspecyfikacji, ale wolałbym nie mieć wielu kopii, chyba że jest to absolutnie konieczne.

mc_electron
źródło