I had an issue whereby my reST long_description wasn't getting rendered as HTML when uploaded to PyPI.  Following the instructions here did not work as-is:

http://docs.python.org/dev/distutils/uploading.html#pypi-package-display

It seems that PyPI passes --no-raw (no HTML allowed) to rst2html.py, in which case the guidance would be better updated to read--

$ python setup.py --long-description | rst2html.py --no-raw > output.html

There are more checks applied in PyPI than just the refusal to incorporate raw html. I doubt it is possible to perform the exact same check with the rst2html command line.

Thanks.  Then perhaps the documentation can be updated to make that clear.

Currently, the documentation implies that running the given command is sufficient to catch all errors, which can lead to confusion when warning-free content is not rendered as HTML.

In 2.7 and newer “setup.py check” is a better interface than rst2html.  +1 to list all checks performed by PyPI on some wiki or PyPI doc page (and +1 to add the same checks in distutils2’s check command).

Éric: your request is in passive voice. I'm not aware that anybody volunteered document the tests, but I doubt that this wiki page can reasonably be kept up-to-date. So the wiki page will outdate just as the current documentation got outdated.

Incorporating the check into distutils 2 is more feasible, but would still require someone to incorporate updates when we make them. The code is (currently) at

https://bitbucket.org/loewis/pypi/raw/default/description_utils.py

Another way to make it easier for users to run the same command as PyPI locally -- also phrased in the passive voice :) -- would be if PyPI packaged its conversion code as a separate module that could also be run as a stand-alone script, and then relied on that.  That would eliminate the need to keep different code bases in synch.

Does the proposed patch to the documentation look okay given the way things are today?

I can open an issue on the PyPI tracker to discuss the broader issue or, if you prefer, on the main Python tracker.

Chris, can you please submit a contrib form? Thanks.

I did yesterday.  I will post here when I receive a response.

Ah, ok. Processing may take some time.

I created issue 15266 for the broader issue.  The corresponding issue I made earlier on the PyPI tracker is also referenced there.

Martin, FYI, Pat processed my contrib form.

The patch looks reasonable to me. Martin/Éric - any objections to committing?

LGTM

Committed in f315cfa22630

Thanks a lot, Eli.

It seems to me there are missing words in the text, and it needs porting to the packaging docs.

Proposal: [...] being able to run the command above without warnings is not sufficient to be sure that PyPI will convert the content successfully.

Éric - what is missing?

Compare:

running the command above without warnings is not sufficient for PyPI to convert the content successfully.

being able to run the command above without warnings is not sufficient to be sure that PyPI will convert the content successfully.

Feel free to change it, I don't mind. I think the intention is clear anyway.

Is there any way I could assist in closing this, perhaps by preparing patches for the Distutils and Distutils2 components?  Can someone point me to where the changes to those components should be made (e.g. where they are located)?

distutils are in Lib/distutils. Distutils2 has been removed from Python.

Thanks, Martin.  Should Distutils2 be removed from the "Components" list of the tracker form, then?  Or was Éric referencing a third-party location?

> Should Distutils2 be removed from the "Components" list of the tracker form, then? 

No. Please stick to one issue at a time, and distutils2 may come back (google for details).

> No. Please stick to one issue at a time, and distutils2 may come back (google for details).

I was asking only to determine whether to create a new issue -- not to have that issue addressed here.

> It seems to me there are missing words in the text, and it needs porting to the packaging docs.

Okay, I misunderstood and thought there was more to do.  Since Martin said packaging has been removed, all that is left is to add Éric's requested modifications to 3.3 (and make the collected change to 2.7 and 3.2).

Patch attached.  The commit message can be something like:

Issue #15231: minor adjustment to prior fix committed in f315cfa22630 regarding, "update PyPI upload doc to say --no-raw passed to rst2html.py."

I included a Misc/NEWS entry since that was left out of the previous commit.

Also, incidentally, there was a typo in the issue number of the commit message for the previous commit, which explains why Roundup did not post here.

I won't be able to work on this for the next few months. This took too much time already.

Since Martin is busy, is there anything I can do to help close this very minor change?  It seems to be in a half-committed state right now.

New changeset 3a08d766eee3 by Eli Bendersky in branch 'default':
Issue #15231: rephrase the last paragraph slightly
http://hg.python.org/cpython/rev/3a08d766eee3

I've committed a rephrase [the Misc/NEWS entry is IMHO unnecessary for tiny documentation clarifications].

Since there's no distutils2/packaging in 3.3 at the moment, I think we're done. Éric - would you like to keep this issue alive to remember applying the fix to packaging, once it's back?

Thanks, Eli.  I know Éric had marked in the tracker for the change to be done in 2.7 and 3.2 as well.

Yes, if the new phrasing looks OK I will backport to 3.2 & 2.7

Please backport and leave open for distutils2.  I much prefer that bugs stay open for months rather than porting to d2 be forgotten.  Thanks.

> Please backport and leave open for distutils2.

Éric, is there a place where updates to the distutils2 docs can be viewed and made prior to reinclusion in the main Python repo?  For example, the documentation here:

http://packages.python.org/Distutils2/devresources.html#documentation

suggests that the documentation is in a docs/source directory of this repo:

http://hg.python.org/distutils2

but I don't seem to see the documentation there.  Or do all changes need to wait for reinclusion?

New changeset 29bdbcadf299 by Eli Bendersky in branch '2.7':
Issue #15231: update PyPI upload doc to say --no-raw passed to rst2html.py
http://hg.python.org/cpython/rev/29bdbcadf299

Backported in 014b36383a54 and 29bdbcadf299

My job is done here. Éric - assigning to you for distutils2, once it becomes relevant.

There’s no more distutils2 to port to, so this is done.