sphinxはルートドキュメントの下のディレクトリにないドキュメントにリンクできますか? -これは結果のSphinx htmlのように、プロジェクトの_README.md
_をSphinxドキュメントに含めたいドキュメンテーションようこそページの目次のリンクをクリックして、_README.md
_にアクセスします。
そのために、行を含むドキュメント_readme_link.rst
_が作成されます
_Readme File
-----------
.. include:: ../../README.md
_
そして、私は行を追加します
_README <readme_link>
_
_index.rst
_のtoctreeへ。それに伴い、_README.md
_はMarkdownとして解析されず、ページにそのままテキストとして印刷されます。
代わりに、マークダウンファイル_readme_link.md
_を使用することも考えられますが、マークダウン付きのファイルを含める方法はありません。
README.mdをマークダウンとして解析するにはどうすればよいですか?
(もちろん、.rstに書き換えたくありません。)
。rstファイル内のマークダウンファイルからの出力をレンダリングする を実行しようとしましたが、これは機能しません。私の_README.md
_には次のような見出しがあります
_# First heading
some text
## Second heading 1
some text
## Second heading 2
some text
_
エラーWARNING: ../README.md:48: (SEVERE/4) Title level inconsistent:
が表示されます。 "Title level inconsistent"はどういう意味ですか? から理解しますが、他の記号を使用する必要がありますが、それらを読むと、答えがrst
記号を指していることがわかりました。それは、私のマークダウンREADMEが実際にrst
に変換されなかったことを意味します。
PS:そのようなことを試みた誰かは https://muffinresearch.co.uk/selectively-include-parts-readme-rst-in-your-docs/
次のようにreadme_link.rst
を編集する必要があります。
Readme File
===========
.. mdinclude:: ../../README.md
セクションヘッダーは、=
文字ではなく-
文字で指定されていることに注意してください。
これに寄与する2つの要因があります。
標準のinclude
(mdinclude
ではない)は、実際にソースファイルの内容を読み取り、ディレクティブの代わりに生のテキストを単にコピーします。 M2Rのmdinclude
は最初にソースのマークダウンテキストをrst
に変換し、次にinclude
と同様に、ディレクティブの代わりにそのテストをコピーします。
したがって、rst
ドキュメントが解析されるまでに、親ファイルとインクルードファイルの両方から1つの完全なrst
ドキュメントが作成されます。その1つの完全なドキュメントは、validrst
ドキュメントである必要があります。
リマインダーとして、 reStructuredText Spec の説明:
セクションタイトルの装飾スタイルに固定数と順序を課すのではなく、施行される順序が発生した順序になります。最初に検出されるスタイルは最も外側のタイトル(HTML H1など)、2番目のスタイルはサブタイトル、3番目のスタイルはサブサブタイトルなどになります。
...
すべてのセクションタイトルスタイルを使用する必要はなく、特定のセクションタイトルスタイルを使用する必要もありません。ただし、ドキュメントはセクションタイトルの使用において一貫している必要があります。タイトルスタイルの階層が確立されると、セクションはその階層を使用する必要があります。
したがって、含まれる子のヘッダーレベルは、親のヘッダーレベルと一致している必要があります。 M2Rはrst
ドキュメントを生成するため、(エンドユーザーとして)各セクションレベルの定義に使用される文字を特定できません。したがって、一貫性を維持するには、 M2Rで定義されたスキーム を使用する必要があります。
- Rst見出しマークは現在ハードコードされており、変更できません。
- H1:
=
、H2:-
、H3:^
、H4:~
、H5:"
、H6:#
ご覧のとおり、レベル1ヘッダーは=
文字を使用し、レベル2ヘッダーは-
文字を使用します。したがって、親readme_link.rst
ファイルで同じスキームを使用する必要があります(逆を使用していました)。
ReStructuredText仕様にも次のように記載されています。
下線のみの装飾スタイルは、同じ文字を使用する上線と下線のスタイルとは異なります。
したがって、親ドキュメントで上線と下線のスタイルを使用できます。M2Rが下線のみのスタイルを使用しているように見えるため、どのレベルでどの文字を使用したかは関係ありません。したがって、これも同様に機能します:
-----------
Readme File
-----------
.. mdinclude:: ../../README.md
これには、含まれている子ドキュメント内のすべてのヘッダーが独自のレベルよりも1レベル低くなるという追加の利点(またはマイナス-あなたの観点によってはマイナス)があります。したがって、子は、より意味的に親に「ネスト」されます(技術的には「有効」ですが、単一のHTMLドキュメント内の複数のh1
が意味的ではないと見なされることがよくあります)。もちろん、これはあなたが望むものかもしれませんし、そうでないかもしれません。それが「代替ソリューション」とラベル付けされている理由です。
別のファイルとしてプロジェクトにマークダウンドキュメントのみを含める場合(およびそのファイルの内容を.rst
ファイルに埋め込む必要がない場合)、代替アプローチがあります。
(これらの手順は、受け入れられた答えにも必要です。)
1.1マークダウンレンダラーがインストールされていることを確認してください:
$ pip install -U sphinx>=1.8.3 recommonmark>=0.5.0
1.2 recommonmark
をconf.py
のextensions
のリストに追加します
1.3マークダウンファイルへのシンボリックリンクを作成する
$ cd docs # or docs/source
$ ln -s ../README.md # or to ../../README.md if using docs/source
toctree
内のファイルをリンクします:
.. toctree::
:maxdepth: 2
:caption: Contents:
source/README.md