Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Mention not using Sphinx extensions in "Making a PyPI-friendly README" #562

Merged
merged 1 commit into from Oct 5, 2018
Merged
Changes from all commits
Commits
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.

Always

Just for now

@@ -14,7 +14,7 @@ For your README to display properly on PyPI, choose a markup language supported
Formats supported by `PyPI's README renderer <https://github.com/pypa/readme_renderer>`_ are:

* plain text
* `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
* `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ (without Sphinx extensions)
* Markdown (`GitHub Flavored Markdown <https://github.github.com/gfm/>`_ by default,
or `CommonMark <http://commonmark.org/>`_)

@@ -88,6 +88,12 @@ Validating reStructuredText markup

If your README is written in reStructuredText, any invalid markup will prevent
it from rendering, causing PyPI to instead just show the README's raw source.

Note that Sphinx extensions used in docstrings, such as
`directives and roles <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
(e.g., "``:py:func:`getattr```" or "``:ref:`my-reference-label```"), are not allowed here and will result in error
messages like "``Error: Unknown interpreted text role "py:func".``".

You can check your README for markup errors before uploading as follows:

1. Install the latest version of `twine <https://github.com/pypa/twine>`_;
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.