[python] 스핑크스는 루트 문서 아래의 디렉토리에없는 문서에 링크 할 수 있습니까?

Program / 글쓴이

비 Python 프로젝트를 문서화하기 위해 Sphinx를 사용하고 있습니다. ./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에 파일을 포함하려고했습니다 . 

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

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

그러나이 오류 메시지는 다음과 같습니다.

경고 : toctree에 존재하지 않는 문서 u’modules / module1 / docs / module1 ‘에 대한 참조가 있습니다.

../어떻게 든 문서 경로에서 사용할 수 없습니까?

업데이트 : conf.py 위치 추가

업데이트 : 아래의 포함 트릭 외에 이것은 여전히 ​​(2019) 불가능합니다. 계속 진행되는 미해결 문제가 있습니다 : https://github.com/sphinx-doc/sphinx/issues/701

답변

그래 넌 할수있어!

심볼릭 링크 (Windows에서는 작동하지 않음) 대신 .. include::지시문 만있는 스텁 문서를 만듭니다 .

소스 트리의 맨 위에있는 README 파일에 연결하려고 시도했습니다. 다음을 파일에 넣습니다 readme_link.rst.

.. include:: ../README

그런 다음에서 index.rsttoctree를 다음과 같이 만들었습니다.

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

이제 색인 페이지에 릴리스 정보에 대한 링크가 있습니다.

제안에 대해 http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html 에 감사드립니다.

답변

대답은 ‘아니요’인 것 같습니다. toc-tree에 나열된 문서는 소스 디렉토리 , 즉 마스터 문서 및 conf.py(및 모든 하위 디렉토리)를 포함하는 디렉토리 내에 있어야합니다 .

로부터 스핑크스-dev에 메일 링리스트 :

STScI에서 우리는 Sphinx의 개별 프로젝트에 대한 문서를 작성한 다음 이러한 다른 프로젝트 별 문서를 포함하는 (toctree 사용) “마스터 문서”도 생성합니다. 이를 위해 toctree는 실제로 문서 소스 트리 외부의 파일을 포함하고 싶지 않은 것처럼 보이기 때문에 마스터 문서의 문서 소스 디렉토리에 프로젝트의 문서 소스 디렉토리에 대한 심볼릭 링크를 만듭니다.

shutil따라서을 사용하여 파일을 복사하는 대신 Project/docs/spec디렉토리의 모든 모듈에 심볼릭 링크를 추가 할 수 있습니다. 심볼릭 링크를 만들면 Project/modulestoc-tree에서 이러한 파일을 간단히 참조 할 수 있습니다 modules/module1/docs/module1.

답변

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

그런 다음 평소와 같이 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:

답변

root에 index.rst 파일 만 있고 Project / docs의 다른 모든 sphinx 항목을 갖도록 sphinx를 구성 할 수도 있습니다.

Windows의 경우 모든 스핑크스 파일과 디렉토리 (index.rst 제외)를 docs /로 이동하고 변경했습니다.

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

답변

나는 외부 jupyter 노트북을 포함하고 싶었던 차이점으로 매우 유사한 문제를 해결했습니다. nbsphinx를 설치했지만 작동하지 못했습니다.
작동하지 않은 것 :

  1. 경로에 루트를 포함하고 싶은 디렉토리가 있습니다.

    conf.py :

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

  2. .. include:: directive파일 사용은 문서에 포함되어 있지만있는 그대로입니다.

마지막으로 문제를 해결 한 것은 nbsphinx-link 패키지를 설치하는 것이 었습니다.

답변

백업하는 상대 링크를 사용하는 것이 정말 불가능한 경우 한 가지 해결책 은 파일을 사양에 대한 사양 폴더 트리에 복사하는 데 ../사용할 수 있지만 절대적으로 필요한 경우가 아니면 여러 복사본을 갖고 싶지 않은 것입니다.shutilconf.py

답변