web-dev-qa-db-ja.com

マークダウンを含めるREADME=にSphinx

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に書き換えたくありません。）

m2r が機能しない理由

。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/

pythonmarkdownpython-sphinxrestructuredtext
15
Make42

次のように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が意味的ではないと見なされることがよくあります）。もちろん、これはあなたが望むものかもしれませんし、そうでないかもしれません。それが「代替ソリューション」とラベル付けされている理由です。

12
Waylan

別のファイルとしてプロジェクトにマークダウンドキュメントのみを含める場合（およびそのファイルの内容を.rstファイルに埋め込む必要がない場合）、代替アプローチがあります。

1.必要な前提条件があることを確認します

（これらの手順は、受け入れられた答えにも必要です。）

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

2.ドキュメントに必要なマークダウンファイルを含めます

toctree内のファイルをリンクします：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   source/README.md
11
Shon