パッケージを Python Package Index ( https://pypi.python.org/pypi ) に送信すると、有効な reStructuredText で記述され、README.rst として保存された README ファイルが、書式設定なしのプレーン テキストとして表示されます。
バリデーター (rstctl および collective.checkdocs) で実行しましたが、エラーは返されません。
私のパッケージは https://pypi.python.org/pypi/lcinvestorにあります。
github にあります: https://github.com/jgillick/LendingClubAutoInvestor
リンクに関する @sigmavirus からの回答は近かったことが判明しました。distutils メーリング リストで議論を始めたところ、ページ内リンク (つまり #minimum-cash) は pypi reStructuredText パーサーでは許可されておらず、ドキュメント全体が無効になることがわかりました。
pypi はホワイトリストを使用してリンク プロトコル (http vs ftp vs gopher) をフィルタリングし、「#」を無効なプロトコルと見なしているようです。これは彼らの側で修正するのはかなり簡単に思えますが、それまでは、ページ内のアンカー リンクを削除します。
collective.checkdocspackage を使用して、無効な構造を検出できます。
pip install collective.checkdocs
python setup.py checkdocs
次に、次の python 関数を使用して、 sphinx のみの構成要素を除外できます (コンテンツに一致させるために、さらに正規表現を追加する必要がある場合があります)。
#!/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)),
sedまたは、このファイルで unix-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