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

Conversation

@wcooley
Copy link
Contributor

wcooley commented Oct 4, 2018

I thought I was doing the right thing by including Sphinx cross-references
in my README.rst and through that in my package's long_description, but only after
several failed validations and searching did I learn that Sphinx extensions are not allowed.

The error message from twine check (or rst-lint) is not obvious about what is wrong: e.g.,
'Error: Unknown interpreted text role "py:func".' and to those just figuring out Sphinx and rST
the distinction is not necessarily obvious.

(I am submitting this PR against "master" because the other 2 open PRs do that; I read the contributing guide but it gave no advice about which branch to use.)

I thought I was doing the right thing by including [Sphinx cross-references](http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects)
in my `README.rst` and through that in my package's `long_description`, but only after
several failed validations and searching did I learn that Sphinx extensions are not allowed.

The error message from `twine check` (or `rst-lint`) is not obvious about what is wrong: e.g.,
'Error: Unknown interpreted text role "py:func".' and to those just figuring out Sphinx and rST
the distinction is not necessarily obvious.
@theacodes theacodes merged commit 3ea6dd3 into pypa:master Oct 5, 2018
1 check passed
1 check passed
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@theacodes

This comment has been minimized.

Copy link
Member

theacodes commented Oct 5, 2018

Thanks, @wcooley!

@webknjaz

This comment has been minimized.

Copy link
Member

webknjaz commented Oct 5, 2018

@wcooley please also note that the opposite might be useful: you can include parts of your readme into sphinx docs and it might be useful to add some markers in README, which won't be rendered :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.