classification
Title: update PyPI upload doc to say --no-raw passed to rst2html.py
Type: Stage: resolved
Components: Distutils, Distutils2, Documentation Versions: Python 3.4, Python 3.3, Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: alexis, chris.jerdonek, docs@python, eric.araujo, python-dev, tarek
Priority: normal Keywords: easy, patch

Created on 2012-07-01 02:34 by chris.jerdonek, last changed 2014-03-12 10:08 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
issue-15231-1.patch chris.jerdonek, 2012-07-06 02:14 review
issue-15231-2.patch chris.jerdonek, 2012-07-28 23:05
Messages (37)
msg164445 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-01 02:34
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
msg164455 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-01 08:01
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.
msg164466 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-01 09:35
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.
msg164734 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-07-06 16:27
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).
msg164739 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-06 17:28
É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
msg164743 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-06 17:52
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.
msg164746 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-06 19:34
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.
msg164747 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-06 19:45
Chris, can you please submit a contrib form? Thanks.
msg164751 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-06 19:56
I did yesterday.  I will post here when I receive a response.
msg164752 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-06 20:02
Ah, ok. Processing may take some time.
msg164760 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-06 22:46
I created issue 15266 for the broader issue.  The corresponding issue I made earlier on the PyPI tracker is also referenced there.
msg165040 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-08 22:18
Martin, FYI, Pat processed my contrib form.
msg166307 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-07-24 16:34
The patch looks reasonable to me. Martin/Éric - any objections to committing?
msg166308 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-24 16:40
LGTM
msg166312 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-07-24 17:01
Committed in f315cfa22630
msg166314 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-24 17:12
Thanks a lot, Eli.
msg166317 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-07-24 17:31
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.
msg166539 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-07-27 03:58
Éric - what is missing?
msg166568 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-07-27 14:05
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.
msg166626 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-07-28 04:48
Feel free to change it, I don't mind. I think the intention is clear anyway.
msg166690 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-28 20:27
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)?
msg166692 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-28 21:06
distutils are in Lib/distutils. Distutils2 has been removed from Python.
msg166695 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-28 21:37
Thanks, Martin.  Should Distutils2 be removed from the "Components" list of the tracker form, then?  Or was Éric referencing a third-party location?
msg166696 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-28 21:40
> 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).
msg166699 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-28 23:05
> 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.
msg166701 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-28 23:58
I won't be able to work on this for the next few months. This took too much time already.
msg166949 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-31 03:00
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.
msg166950 - (view) Author: Roundup Robot (python-dev) Date: 2012-07-31 03:15
New changeset 3a08d766eee3 by Eli Bendersky in branch 'default':
Issue #15231: rephrase the last paragraph slightly
http://hg.python.org/cpython/rev/3a08d766eee3
msg166951 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-07-31 03:17
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?
msg166953 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-31 03:23
Thanks, Eli.  I know Éric had marked in the tracker for the change to be done in 2.7 and 3.2 as well.
msg166955 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-07-31 03:28
Yes, if the new phrasing looks OK I will backport to 3.2 & 2.7
msg167060 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-07-31 22:25
Please backport and leave open for distutils2.  I much prefer that bugs stay open for months rather than porting to d2 be forgotten.  Thanks.
msg167113 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-01 10:26
> 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?
msg167179 - (view) Author: Roundup Robot (python-dev) Date: 2012-08-02 00:00
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
msg167180 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-08-02 00:01
Backported in 014b36383a54 and 29bdbcadf299
msg167768 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-08-09 07:52
My job is done here. Éric - assigning to you for distutils2, once it becomes relevant.
msg213235 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-12 10:08
There’s no more distutils2 to port to, so this is done.
History
Date User Action Args
2014-03-12 10:08:32eric.araujosetstatus: open -> closed
resolution: fixed
messages: + msg213235

stage: commit review -> resolved
2012-08-09 07:52:29eli.benderskysetnosy: - eli.bendersky
2012-08-09 07:52:07eli.benderskysetassignee: docs@python -> eric.araujo
messages: + msg167768
nosy: tarek, eric.araujo, eli.bendersky, chris.jerdonek, docs@python, alexis, python-dev
2012-08-02 00:01:34eli.benderskysetmessages: + msg167180
2012-08-02 00:00:58python-devsetmessages: + msg167179
2012-08-01 10:26:48chris.jerdoneksetmessages: + msg167113
2012-07-31 22:25:07eric.araujosetmessages: + msg167060
2012-07-31 03:28:43eli.benderskysetmessages: + msg166955
2012-07-31 03:23:30chris.jerdoneksetmessages: + msg166953
2012-07-31 03:17:53eli.benderskysetmessages: + msg166951
2012-07-31 03:15:18python-devsetnosy: + python-dev
messages: + msg166950
2012-07-31 03:00:24chris.jerdoneksetmessages: + msg166949
2012-07-28 23:58:54loewissetnosy: - loewis
2012-07-28 23:58:39loewissetmessages: + msg166701
2012-07-28 23:05:13chris.jerdoneksetfiles: + issue-15231-2.patch

messages: + msg166699
2012-07-28 21:40:16loewissetmessages: + msg166696
2012-07-28 21:37:08chris.jerdoneksetmessages: + msg166695
2012-07-28 21:06:54loewissetmessages: + msg166692
2012-07-28 20:27:46chris.jerdoneksetmessages: + msg166690
2012-07-28 04:48:05eli.benderskysetmessages: + msg166626
2012-07-27 14:05:23eric.araujosetmessages: + msg166568
2012-07-27 03:58:03eli.benderskysetmessages: + msg166539
2012-07-24 17:31:56eric.araujosetstatus: closed -> open

components: + Distutils, Distutils2
versions: + Python 2.7, Python 3.2, Python 3.4
nosy: + alexis, tarek

messages: + msg166317
resolution: fixed -> (no value)
stage: resolved -> commit review
2012-07-24 17:12:42chris.jerdoneksetmessages: + msg166314
2012-07-24 17:01:49eli.benderskysetstatus: open -> closed
resolution: fixed
messages: + msg166312

stage: patch review -> resolved
2012-07-24 16:40:28loewissetmessages: + msg166308
2012-07-24 16:34:33eli.benderskysetnosy: + eli.bendersky
messages: + msg166307
2012-07-08 22:18:38chris.jerdoneksetmessages: + msg165040
2012-07-06 22:46:04chris.jerdoneksetmessages: + msg164760
2012-07-06 20:02:31loewissetmessages: + msg164752
2012-07-06 19:56:14chris.jerdoneksetmessages: + msg164751
2012-07-06 19:45:27loewissetmessages: + msg164747
2012-07-06 19:34:15chris.jerdoneksetmessages: + msg164746
2012-07-06 17:52:36chris.jerdoneksetmessages: + msg164743
2012-07-06 17:28:15loewissetmessages: + msg164739
2012-07-06 16:27:02eric.araujosetnosy: + eric.araujo
messages: + msg164734
2012-07-06 02:14:26chris.jerdoneksetfiles: + issue-15231-1.patch
keywords: + patch
stage: patch review
2012-07-01 09:35:26chris.jerdoneksetmessages: + msg164466
2012-07-01 08:01:34loewissetnosy: + loewis
messages: + msg164455
2012-07-01 02:34:33chris.jerdonekcreate