我的rst自述文件未在pypi.python.org上格式化

Question

当我将包提交到Python包索引（https://pypi.python.org/pypi）时，我的自述文件（使用有效的StructuredText编写并保存为README.rst）显示为纯文本，没有任何格式

我已经通过验证器（rstctl和collective.checkdocs）运行了它，没有返回任何错误

我的包裹在： https://pypi.python.org/pypi/lcinvestor

它位于github的以下位置： https://github.com/jgillick/LendingClubAutoInvestor

Answer 1

编辑：您可以使用以下方法查找RST中的错误，这些错误将显示在PyPI上：

twine check

您需要twine版本1.12.0或更高版本。如果没有，可以使用以下方法安装或更新：

pip install --upgrade twine

Source

---

不推荐的答案：

python setup.py check --restructuredtext

Source

Answer 2

事实证明，@sigmavirus关于这些联系的答案很接近。我在distutils邮件列表上启动了一个discussion，发现pypi-reStructuredText解析器不允许页面内链接（即#最小现金），并将使整个文档无效

pypi似乎使用白名单过滤链接协议（http、ftp和gopher），并将“#”视为无效协议。这看起来很容易修复，但在此之前，我将删除我的页面内锚链接

Answer 3

• 您可以使用^{}包来检测无效的构造：

  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实用程序用于此文件：

## 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