当我将我的包提交到Python包索引（https://pypi.python.org/pypi）时，我的README文件（使用有效的reStructuredText编写并保存为README.rst）显示为纯文本而没有任何格式。
我通过验证器（rstctl和collective.checkdocs）运行它，并且没有返回任何错误。
我的包裹在： https://pypi.python.org/pypi/lcinvestor
这是在github： https://github.com/jgillick/LendingClubAutoInvestor
答案 0 :(得分：26)
事实证明@sigmavirus关于链接的答案很接近。我在distutils邮件列表上启动了discussion，发现pypi reStructuredText解析器不允许页内链接（即#minimum-cash），并且会使整个文档无效。
似乎pypi使用白名单过滤链接协议（http vs ftp vs gopher），并将'＃'视为无效协议。看起来这很容易修复它们，但在那之前，我将删除我的页内锚链接。
答案 1 :(得分：22)
您可以使用collective.checkdocs包来检测无效的结构：
pip install collective.checkdocs
python setup.py checkdocs
然后，您可以使用以下python函数过滤掉仅限sphinx的构造（可能需要添加更多正则表达式以匹配您的内容）：
< / LI>#!/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
答案 2 :(得分：12)
答案 3 :(得分：8)
我弹出的第一件事（快速扫描后）是在高级过滤器部分中，在链接后使用两个下划线，例如，
`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
------------------------------------------------------
答案 4 :(得分：4)
将python模块上传到pypi时遇到了同样的问题。
后来我使用 rst-lint 检查了 README.rst 的错误，这表明我的自述文件是正确的。
我发现问题不在README文件中，而是在 setup.py 本身。