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

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

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ę

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.

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:

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('..'))

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

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.