When I submit my package to the Python Package Index (https://pypi.python.org/pypi) my README file, which is written with valid reStructuredText and saved as README.rst, is displayed as plain text without any formatting.
I have run it through validators (rstctl and collective.checkdocs) and no errors are returned.
My package is at: https://pypi.python.org/pypi/lcinvestor
It's in github at: https://github.com/jgillick/LendingClubAutoInvestor
事实证明，@sigmavirus 关于链接的答案很接近。我开始讨论distutils 邮件列表，发现 pypi reStructuredText 解析器不允许页内链接（即#minimum-cash），这将使整个文档无效。
似乎 pypi 使用白名单来过滤链接协议（http vs ftp vs gopher），并将“#”视为无效协议。看起来这很容易解决他们的问题，但在那之前，我将删除我的页内锚链接。
您可以使用collective.checkdocs包来检测无效的构造：
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)),
或者，您可以将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
弹出给我的第一件事（快速扫描后）是在您的高级过滤器部分中，您在链接后使用两个下划线，例如，
`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
------------------------------------------------------
将我的 python 模块上传到 pypi 时，我遇到了同样的问题。
后来我检查了README.rst中的错误，rst-lint这表明我的自述文件是正确的。
我发现问题不在 README 文件中，而在setup.py本身。