루트 문서 아래 디렉터리에 없는 문서에 스핑크스를 연결할 수 있습니까?

루트 문서 아래 디렉터리에 없는 문서에 스핑크스를 연결할 수 있습니까?

저는 비 파이썬 프로젝트를 문서화하기 위해 스핑크스를 사용하고 있습니다.는 배하고싶다니를 하고 싶습니다../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 to 과 같이 합니다.

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

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

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

경고: tctree에 존재하지 않는 문서 u'modules/module1/docs/module1'에 대한 참조가 포함되어 있습니다.

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

업데이트: conf.py 위치가 추가되었습니다.

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

네, 할 수 있어요!

링크하지 않음)에, "" (Windows에서는 사용할 수 없음) "" (Windows에서는 사용할 수 없음) "" ... include::direction.

소스 트리의 맨 위에 있는 README 파일에 연결하는 중에 이 문제가 발생했습니다.나는 다음과 같은 파일을 넣었습니다.readme_link.rst:

.. include:: ../README

그럼인에서.index.rst토트리를 다음과 같이 만들었습니다.

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(및 모든 하위 디렉터리).

spinx-dev 메일링 목록에서 다음을 수행합니다.

STScI에서는 스핑크스의 개별 프로젝트에 대한 문서를 작성한 다음, (토트리를 사용하여) 다수의 다른 프로젝트별 문서를 포함하는 "마스터 문서"를 작성합니다.이를 위해 마스터 문서의 문서 원본 디렉터리에 프로젝트의 문서 원본 디렉터리에 대한 심볼 링크를 만듭니다. toctree는 문서 원본 트리 외부에 있는 파일을 포함하지 않는 것 같습니다.

따라서 파일을 복사하는 대신shutil은 당신의 볼 수 있습니다.Project/docs/spec디렉토리입니다.Project/modules그러면 toc-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'))

그런 다음 동일한 디렉토리에 있는 rst 파일을 참조하여 index.rst를 평소와 같이 사용합니다.로컬 스핑크스 폴더의 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:

저는 외장 주피터 노트북을 포함하고 싶었던 차이로 꽤 비슷한 문제를 해결했습니다.나는 nbspinx를 설치했지만 작동하지 않았습니다.작동하지 않는 것:

1. 경로에 루트를 포함할 디렉터리가 있습니다.

   conf.py :

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

2. 사용.. include:: directive파일이 설명서에 포함되었지만 그대로입니다.

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

제 대답은 본질적으로 @Dan Menes입니다. 하지만 재구조화 대신 Myst parser를 위한 것입니다.

나는 이것이 거기에 속해 있기 때문에 @Dan Menes 답변에 댓글로 추가하고 싶지만, 댓글은 내가 포맷을 하는 것을 허용하지 않고, Myst 구문은 새 줄에 민감하고 댓글은 문자가 제한되어 있습니다.그래서 기존 답변과 관련된 경우에도 별도의 답변으로 게시합니다.

Myst에 포함시키려면 형식을 약간 다르게 지정해야 합니다.

```{include} ../main/post_installation_windows.md
```

또한 reStructured 마크업을 수행하기 위해 자체적으로 래핑할 수 있습니다(그 후 포함된 파일은 구조화된 상태로 처리됩니다).

```{eval-rst}
.. include:: snippets/include-rst.rst
```

그러나 기본 Myst 구문을 사용하는 것이 더 쉽습니다.예를 들어, 파일을 포함하는 것만으로는 포함된 파일 내의 참조가 올바르게 해결되지 않지만 include-literal은 다음과 같은 더 나은 기능을 제공합니다.

```{include-literal} ../../example.md
:language: md
```

단순한 문서를 포함하는 것은 괜찮지만, 많은 참조가 있는 복잡한 문서를 포함하는 것은 더 골치 아픈 일이 될 것이기 때문에 실험을 추천합니다.include-literal(버전 0.12.7부터)

참조: https://myst-parser.readthedocs.io/en/latest/using/howto.html

루트에 index.rst 파일만 있고 Project/docs에 있는 다른 모든 스핑크스 항목을 포함하도록 스핑크스를 구성할 수도 있습니다.

윈도우의 경우 모든 스핑크스 파일과 dir(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('..'))

스텁 파일을 생성할 필요가 없는 대체 기술은 절대 참조를 사용하는 것입니다./) 루트 할 때 sphinx-build디렉토리 레이아웃 예:

/path/to/common/ancestor
├── a
│   └── foo.rst
├── b
│   ├── bar.rst
│   ├── x
│   │   └── index.rst
│   └── y
│       └── boz.rst
└── c
    └── baz.rst

그리고.b/x/index.rst:

.. toctree::
   /a/foo
   /b/bar
   /b/y/boz
   /c/baz

그리고 당신의sphinx-build명령은 다음과 같습니다.

sphinx-build -c <confdir> -b html -D masterdoc=b/x/index /path/to/common/ancestor <outdir>

저는 이것을 스핑크스로 테스트했습니다.3.0.2.

의 해결책, 정말로 하는 것이하다면, ㅠㅠㅠㅠㅠㅠㅠㅠㅠㅠㅠㅠㅠㅠㅠ../은▁use있▁that▁i▁is▁could는을 사용할 수 있다는 것입니다.shutil을 파을의 폴트복다의 합니다.conf.py하지만 꼭 필요한 경우를 제외하고는 사본을 여러 개 갖고 싶지 않습니다.

언급URL : https://stackoverflow.com/questions/10199233/can-sphinx-link-to-documents-that-are-not-located-in-directories-below-the-root