スフィンクスRTDのテーマと私のpython 3でライブラリを書かれ、クラス、そのメソッド、定数を文書化する過程で今の私している

Question

改行など

私はある定数の微妙なフォーマットの問題が生じていますリストまたはdicts。

STD_LIST = [ 
    'item1', 
    'item2', 
    'item3', 
] 

：私の組織では、私は、たとえば、リストされているいくつかの定数を持っている私のクラスで一覧表示し、dictsは、読みやすくするために、次の形式で書かれるべき位置...

my_list = [ 
    'One', 
    'Two', 
    'Three', 
] 

my_dict = { 
    'One': 1, 
    'Two': 2, 
    'Three': 3, 
} 

をとっていますこのリストと他のすべてのクラス定数をdocstringクラスにコピーし、それぞれの重要性を説明する段落を書きました。 htmlドキュメントにこのような書式設定が必要な場合は、縦線（ "|"）を使用して新しい行を強制します。

は、ここに私のreStructuredTextのです：

|  **STD_LIST = [** 
|   **'item1',** 
|   **'item2',** 
|   **'item3',** 
|  **]** 

     This list is very important. Please do not modify it unless you know 
     what you are doing. Best not to touch it ever! 

     .. warning:: Don't touch :py:const:`STD_LIST` unless you know what \ 
     you are doing. 

しかし、その後、次のようになります。ここ

問題、私は微妙言ったように、ですが、私は完璧主義者のようなものです。通常の定数が文書化されると、記述は字下げされます。縦棒を使用すると、このくぼみが乱されます。 （下の画像と比較する） 定数宣言と説明の間の空白行を削除すると、リストの最後の行で説明が継続されることがわかりました。説明の最初の行に垂直バーを追加すると、この問題は完全に修正されますが、その間に空白行を追加しないことで、次の定数の問題が発生します。

誰でもこのような場合にreSTとSphinxとの一貫性をどのように達成するかを知っていますか？私はこのdocstringの定数間の改行を強制することも適切な回避策になると考えています。

Answer 1

私は自分の質問を入力してから、何かを試してみる必要がありました。ソリューションが他の人に役立つことを願っています。私の答えは面倒ですが、うまくいきます。誰かがより良い解決策を持っているなら、投稿してください！

明らかに問題は、定数の宣言とその使用の説明との間に空白の行があったようです。空白行を削除します。

しかし、これにより、説明の最初の行が説明の最初の行と同じ行に表示されていました。これを解決するには、説明の最初の行に垂直バーを追加します。

しかし、これは定数と1つ後のものとの間に実質的に空白スペースがないため、迷惑でした。だから私は、説明の後の行にそれ自身の行にさらに別の垂直バーを追加することによって、新しい行を強制しなければならなかった。

|  **STD_LIST = [** 
|   **'item1',** 
|   **'item2',** 
|   **'item3',** 
|  **]** 
|   This list is very important. Please do not modify it unless you know 
      what you are doing. Best not to touch it ever! 

      .. warning:: Don't touch :py:const:`STD_LIST` unless you know what \ 
      you are doing. 
| 

    **NEXT_CONST = 'Stackoverflow.com is amazing!'** 
     A shoutout to the stackoverflow.com admins and users. This is a normal constant 
     string and doesn't need any vertical bar trickery to get Sphinx to format it 
     nicely. 

次はきれいにフォーマット出力であり、まさに私が探していた：

例外：ここでは、最終的な解決策だ記述が訓戒を終了すると垂直を追加する必要はありません警戒の後にバー。代わりに、テキストの説明の後にラインに垂直バーを移動して、そのような訓戒の前に空白行を含める：

|  **STD_LIST = [** 
|   **'item1',** 
|   **'item2',** 
|   **'item3',** 
|  **]** 
|   This list is very important. Please do not modify it unless you know 
      what you are doing. Best not to touch it ever! 
| 

      .. warning:: Don't touch :py:const:`STD_LIST` unless you know what \ 
      you are doing. 

    **NEXT_CONST = 'Stackoverflow.com is amazing!'** 
     A shoutout to the stackoverflow.com admins and users. This is a normal constant 
     string and doesn't need any vertical bar trickery to get Sphinx to format it 
     nicely. 

Answer 2

私はcode-blockおよびその他のマークアップを使用します。私はコードではないので、物語の文書の段落に改行を使用しません。行の長さが変化してPEP8に準拠するように変更されたときの差分は苦痛です。 PEP8は、物語の文書化には完全に不要です。 reStructuredTextソースではなく、PEP8をPythonコードに保存してください。

Some introductory text about ``STD_LIST``. 

    .. code-block:: python 

     STD_LIST = [ 
      'item1', 
      'item2', 
      'item3', 
     ] 

    This list is very important. Please do not modify it unless you know what you are doing. Best not to touch it ever! 

    .. warning:: 

     Don't touch :py:const:`STD_LIST` unless you know what you are doing. 

Some introductory text about ``NEXT_CONST``. 

    .. code-block:: python 

     NEXT_CONST = 'Stackoverflow.com is amazing!' 

    A shoutout to the stackoverflow.com admins and users. This is a normal constant string and doesn't need any vertical bar trickery to get Sphinx to format it nicely. 

ここでは入札されたreStructuredTextがHTMLです。