web-dev-qa-db-ja.com

私の最初のREADMEはpypi.python.orgでフォーマットされていません

パッケージをPython Package Index（ https://pypi.python.org/pypi ）my README有効なreStructuredTextで書き込まれ、README.rstとして保存されたファイルは、フォーマットなしでプレーンテキストとして表示されます。

バリデーター（rstctlとcollective.checkdocs）を介して実行しましたが、エラーは返されません。

私のパッケージは次の場所にあります： https://pypi.python.org/pypi/lcinvestor

Githubの次の場所にあります： https://github.com/jgillick/LendingClubAutoInvestor

python-2.7pypi
47
Jeremy Gillick

リンクに関する@sigmavirusからの回答は近いことがわかりました。 distutilsメーリングリストで discussion を開始しましたが、ページ内リンク（つまり、＃minimum-cash）がpypi reStructuredTextパーサーで許可されておらず、ドキュメント全体が無効になることがわかりました。

Pypiはホワイトリストを使用してリンクプロトコル（http vs ftp vs Gopher）をフィルタリングし、「＃」を無効なプロトコルと見なしているようです。これは彼らの側でかなり簡単に修正できるようですが、それまでは、ページ内のアンカーリンクを削除します。

26
Jeremy Gillick

  • collective.checkdocs 無効な構成を検出するパッケージ：

    pip install collective.checkdocs python setup.py checkdocs

  • 次に、次のpython関数を使用して、sphinx-only構造をフィルターで除外できます（追加する必要がある場合があります）あなたのコンテンツに一致するように、より多くの正規表現）：

#!/usr/bin/python3
"""
Cleans-up Sphinx-only constructs (ie from README.rst),
so that *PyPi* can format it properly.

To check for remaining errors, install ``sphinx`` and run::

        python setup.py --long-description | sed -file 'this_file.sed' | rst2html.py  --halt=warning

"""

import re
import sys, io


def yield_sphinx_only_markup(lines):
    """
    :param file_inp:     a `filename` or ``sys.stdin``?
    :param file_out:     a `filename` or ``sys.stdout`?`

    """
    substs = [
        ## Selected Sphinx-only Roles.
        #
        (r':abbr:`([^`]+)`',        r'\1'),
        (r':ref:`([^`]+)`',         r'`\1`_'),
        (r':term:`([^`]+)`',        r'**\1**'),
        (r':dfn:`([^`]+)`',         r'**\1**'),
        (r':(samp|guilabel|menuselection):`([^`]+)`',        r'``\2``'),


        ## Sphinx-only roles:
        #        :foo:`bar`   --> foo(``bar``)
        #        :a:foo:`bar` XXX afoo(``bar``)
        #
        #(r'(:(\w+))?:(\w+):`([^`]*)`', r'\2\3(``\4``)'),
        (r':(\w+):`([^`]*)`', r'\1(``\2``)'),


        ## Sphinx-only Directives.
        #
        (r'\.\. doctest',           r'code-block'),
        (r'\.\. plot::',            r'.. '),
        (r'\.\. seealso',           r'info'),
        (r'\.\. glossary',          r'rubric'),
        (r'\.\. figure::',          r'.. '),


        ## Other
        #
        (r'\|version\|',              r'x.x.x'),
    ]

    regex_subs = [ (re.compile(regex, re.IGNORECASE), sub) for (regex, sub) in substs ]

    def clean_line(line):
        try:
            for (regex, sub) in regex_subs:
                line = regex.sub(sub, line)
        except Exception as ex:
            print("ERROR: %s, (line(%s)"%(regex, sub))
            raise ex

        return line

    for line in lines:
        yield clean_line(line)

および/またはあなたのsetup.pyファイル、次のようなものを使用します::

def read_text_lines(fname):
    with io.open(os.path.join(mydir, fname)) as fd:
        return fd.readlines()

readme_lines = read_text_lines('README.rst')
long_desc = ''.join(yield_sphinx_only_markup(readme_lines)),

または、次のファイルでsedunix-utilityを使用することもできます。

## Sed-file to clean-up README.rst from Sphinx-only constructs,
##   so that *PyPi* can format it properly.
##   To check for remaining errors, install ``sphinx`` and run:
##
##          sed -f "this_file.txt" README.rst | rst2html.py  --halt=warning
##

## Selected Sphinx-only Roles.
#
s/:abbr:`\([^`]*\)`/\1/gi
s/:ref:`\([^`]*\)`/`\1`_/gi
s/:term:`\([^`]*\)`/**\1**/gi
s/:dfn:`\([^`]*\)`/**\1**/gi
s/:\(samp\|guilabel\|menuselection\):`\([^`]*\)`/``\1``/gi


## Sphinx-only roles:
#        :foo:`bar` --> foo(``bar``)
#
s/:\([a-z]*\):`\([^`]*\)`/\1(``\2``)/gi


## Sphinx-only Directives.
#
s/\.\. +doctest/code-block/i
s/\.\. +plot/raw/i
s/\.\. +seealso/info/i
s/\.\. +glossary/rubric/i
s/\.\. +figure::/../i


## Other
#
s/|version|/x.x.x/gi
22
ankostis

以下を使用して、PyPIに表示されるRSTのエラーを見つけることができます。

python setup.py check --restructuredtext

ソース

13
Serpentine Cougar

（クイックスキャン後に）最初に表示されるのは、[高度なフィルター]セクションで、リンクの後に2つのアンダースコアを使用していることです。

`Link text <http://example.com>`__

あるべき場所

`Link text <http://example.com>`_

ReStructuredTextチェッカーがそれをキャッチしなかったのは奇妙です。 docutilsもインストールされている場合は、rst2html.py README.rstを実行すると、HTMLが出力されます。エラーがある場合は失敗し、エラーがどこにあったかを教えてくれます。

また、公正な警告、リストには先頭にスペースを入れないでください。

 - foo
 - bar

の代わりに

- foo
- bar

（視覚的に明確にするため）

- foo # correct
 - one too many for a regular list, it will show up as a quoted list

また、相対リンクはText to link <#link>_のようには機能しません。別のセクションにリンクする場合は、次のことを行う必要があります。

Here's my `link <section_name>`_ to the other section.

.. Other stuff here ...

.. _section_name:

Min/Max Investment Opportunities and Other Foo Biz Baz
------------------------------------------------------
8
Ian Stapleton Cordasco

私は同じ問題を抱えていました私のpythonモジュールをpypiにアップロードするとき。

後で、README.rstを使用してエラーをチェックしましたrst-lintこれは私のreadmeファイルが正しいことを示しています。

問題はREADMEファイルではなく、setup.py自体にあることがわかりました。

Readmeとsetup.pyを作成するときは、以下の点に従ってください。

  • 複数行を書かないでくださいpython説明や要約、またはsetup（）引数に入る文字列。
  • READMEファイル（./path1/path2など）で相対リンクを使用しないでください。
  • Rst-lintなどのチェックツールを使用して、最初の構文に問題がないことを確認します。
  • マークダウンファイルがある場合は、pandocを使用して簡単に再構築されたテキストに変換できます
4
Natesh bhat