Мой первый README не отформатирован на pypi.python.org

Когда я отправляю свой пакет в Индекс пакетов Python (https://pypi.python.org/pypi), мой файл README, который написан с использованием действительного reStructuredText и сохраняется как README.rst, является отображается как обычный текст без форматирования.

Я запускаю его с помощью валидаторов (rstctl и collect.checkdocs), и никаких ошибок не возвращается.

Мой пакет находится по адресу: https://pypi.python.org/pypi/lcinvestor

В github на: https://github.com/jgillick/LendingClubAutoInvestor

5 ответов

Получается, что ответ от @sigmavirus относительно ссылок был близок. Я начал обсуждение в списке рассылки distutils и выяснил, что ссылки на странице (т.е. # минимальные деньги) не разрешены pypi reStructuredText анализатора и аннулирует весь документ.

Кажется, что 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)),

В качестве альтернативы вы можете использовать утилиту sed unix с этим файлом:

## 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="">`__
</http:>

Где это должно быть

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

Нечетно, что проверки 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 my `link <section_name>`_ to the other section.
.. Other stuff here ...
.. _section_name:
Min/Max Investment Opportunities and Other Foo Biz Baz
------------------------------------------------------
</section_name>


Вы можете использовать следующее, чтобы найти ошибки в вашем RST, которые будут отображаться в PyPI:

python setup.py check --restructuredtext

Источник


У меня была такая же проблема при загрузке моего модуля python в pypi.

Позже я проверил README.rst для ошибок, используя rst-lint, который показал, что мой файл readme прав.

Я обнаружил, что проблема не в файле README, а в setup.py.

Следуйте приведенным ниже пунктам при написании Readme и setup.py

  • НЕ пишите строки python MULTI LINE для описания или резюме или чего-либо, что входит в аргументы setup().
  • Не используйте относительные ссылки в файле README (например./path1/path2).
  • Убедитесь, что первый синтаксис подходит, используя инструмент проверки, например rst-lint.
  • Если у вас есть файл разметки, вы можете преобразовать его в реструктурированный текст с помощью pandoc легко

licensed under cc by-sa 3.0 with attribution.