Switch documentation host

[waylan]

As pointed out in #554 I didn't update the publicly hosted docs with the 2.6.9 release. I now remember that I tried but ran into problems uploading the docs. Then I ran out of time and forgot to come back to it later.

In any event as I explain here:

The homepage at http://pythonhosted.org states:

To upload documentation, go to your package edit page (http://pypi.python.org/pypi?%3Aaction=pkg_edit&name=yourpackage), and fill out the form at the bottom of the page.

However, there is no longer a form at the bottom of the edit page for uploading documentation. Instead I only see:

If you would like to DESTROY any existing documentation hosted at http://pythonhosted.org/ProjectName Use this button, There is no undo.

[Destroy Documentation]

I also went to pypi.org and logged in there. But I don't see any options for editing my projects or uploading documentation on that site.

So, how do I upload an update to my documentation?

In addition to the above, pythonhosted seems to have been rather flakey lately. I'm considering switching to GitHub Pages (probably using Organization Pages so the URL would be https://Python-Markdown.github.io). I'm not interested in readthedocs as they require you to have them build your docs and then we cannot use our own tooling to build our own docs (they do support MkDocs, but an older version with less than complete support for Markdown extensions, which is a nonstarter IMO). Any thoughts?

[mitya57]

In case you want to update the pythonhosted.org page: last time I tried, setuptools’ upload_docs command worked. This means you can either use POST requests directly (see the implementation) or adapt that command to use your custom tarball instead of a Sphinx-generated one.

[waylan]

As a reminder, we are not yet using setuptools, so we don't have the upload_docs command available. We could certainly switch over (the md3 branch already has been), but that doesn't help for a previous release.

However, I do see some value in using the mechanism in that script to upload something redirecting people to the new docs.

[waylan]

According to pypa/setuptools@7f81445 the upload_docs command is deprecated (with a warning suggesting using RTD) and a separate comment indicates that the new "Wharehouse" (pypi.org) will not ever support hosting documentation. Unfortunately, nothing in the commit references a source (like perhaps, an official announcement?), but this isn't the first I've see that suggests pythonhosted.org may be going away completely when the switch from pypi.python.org to pypi.org is complete. My point is that we should switch now before we can't change anything on pythonhosted.org.

[waylan]

After some more searching, AFAICT, the current state of affairs is explained in the discussion in pypi/warehouse#582 (see also pypi/legacy#672 which links to some mailing list discussions). What is clear is that pythonhosted.org will be going away. What's not clear is if we can still update anything there (some comments seem to indicate not).

Given the state of things, I'm proposing the following plan:

1. First, prepare and upload docs to an alternate host (GitHub Pages via MkDocs?)
2. After the alternate host is live (and links are updated where we can), explore updating the existing docs on pyhtonhosted.org to redirect people to the new docs.
3. Finally, at some point in the future, delete the docs from pythonhosted.org.

[waylan]

So I successfully got the upload_docs script to run. However, the upload did not succeed. This was the output:

running upload_docs
Upload_docs command is deprecated. Use RTD instead.
Submitting documentation to https://pypi.python.org/pypi/
Upload failed (410): Gone (This API has been deprecated and removed from legacy PyPI in favor of using the APIs available in the new PyPI.org implementation of PyPI (located at https://pypi.org/). For more information about migrating your use of this API to PyPI.org, please see https://packaging.python.org/guides/migrating-to-pypi-org/#uploading. For more information about the sunsetting of this API, please see https://mail.python.org/pipermail/distutils-sig/2017-June/030766.html)

AFAICT, we can only "delete" the existing documentation. There are no options to update in any way.
Unfortunately, it seems that they skipped from step 1 to step 5 of the roadmap without bothering with steps 2, 3, & 4.

[facelessuser]

Ha, man, I love Python, but some of the PyPI decisions are weird.

[waylan]

For the record, the documentation is now available at https://python-markdown.github.io/.

I used to be able to edit a package's meta-data right in PyPI. Apparently, now the only way to do so is to upload a new release. Therefore, even after all that work, PyPI still points to pythonhosted.org. Guess we need to roll a new release to finalize this.

I'll delete the old docs after PyPI no longer points to them.