Provide packagers with clarification on pythonhosted.org

[cjerdonek]

One question that I'm sure newcomers to packaging have is, "where should I host my documentation?" or "is there an official or preferred place to host my documentation?" (I sure had this question.)

Of course, PyPI displays the package's "long_description" (which is also worth mentioning in the guide), but PyPI also says this on the edit page for a package--

You can now host documentation at http://pythonhosted.org/project_name. To upload documentation, prepare a .zip file that is unpacked into this URL. Only static pages are supported. The zip file must have a top-level "index.html".

I know the Guide tries to avoid taking sides on third-party tools (e.g. test frameworks, etc). But given that pythonhosted.org is owned by PSF and recommended by PyPI, is this a candidate for a recommendation (e.g. on the "Tool Recommendations" page)?

Since pythonhosted.org is more a service rather than a tool, perhaps the page title could be changed to "Tool & Service Recommendations." (PyPI itself is another service that is implicitly recommended on the page; it doesn't have its own bullet point but could under a "Services" section for completeness and clarity.)

[ncoghlan]

Perhaps we could make a meta-recommendation and point folks towards Cookie Cutter if they want more "best practices" ideas? It's really better set up for this kind of thing (although it can create its own flavour of "analysis paralysis" vs "just publish something, and fill in the other details later").

[cjerdonek]

Hmm, I'd rather the Guide not weigh in on where to go to find best practices.

This issue is just a question about pythonhosted.org. Is it the official place for Python documentation in conjunction with PyPI, or is it just a recommendation on PyPI's part? If the latter, this issue can be closed.

[pfmoore]

I thought most projects used http://readthedocs.org?

[cjerdonek]

Yeah, that's partly why I created this issue. After seeing the PyPI notice, I wasn't sure if there was a new "standard" location. If there's no standard location, however, we can close this. @pfmoore, have you seen the text on PyPI I'm referring to? If there's no standard location, I wonder if PyPI should be making a recommendation.

[ncoghlan]

Right, if we were going to recommend anything, Sphinx+ReadTheDocs is actually the easiest option in most cases. Recommending Sphinx is an easy one to justify, since it's the docs system Georg created specifically for the CPython documentation. RTFD was then created as a Django Dash project specifically for Sphinx hosting.

The workflow for using pythonhosted.org is a little less straightforward than the "commit and your docs automatically rebuild" that RTFD offers.

The challenge we face is that we want to give newcomers better places to start than just throwing them at Google unassisted, but at the same time we don't want PyPUG to expand too far into becoming a general "programming best practices" guide. By contrast, projects like Cookie Cutter are specifically about making it easy to share best practices through project templates.

If we bring "Offer pointers to development best practices templating tools" into scope for PyPUG, then I think that makes it easier to enforce the boundary. Templates are also slightly more likely than purely descriptive guides to be kept up to date with a changing environment, especially when they're actively used by contractors and freelancers that are regularly starting new projects for clients.

[pfmoore]

@cjkerdonek No, I hadn't seen that text until you quoted it (is it in the project upload area? it may be relevant that I don't personally have any projects hosted on PyPI...)

As to whether pythonhosted is "the official place" for documentation, I'd have to say no. Too many projects don't use it.

Maybe there should be a section in "Tool Recommendations" called "Hosting Recommendations" or something, that explicitly says "use PyPI to publish details of your package", "use PyPI to host your package files (unless the PyPI terms and conditions aren't appropriate for you" and "use pythonhosting.org for hosting static files related to your project that you don't host anywhere else". At the moment, we don't actually say "use PyPI" anywhere...

[pfmoore]

@ncoghlan +1 on something like a section "Development tool recommendations" that mentions CookieCutter. It would probably be acceptable to also point at Sphinx, because as you say it pretty much is the official documentation tool. I'd steer well clear of recommending a test tool, but mentioning the key options (unittest, pytest, nose and tox, I'd say) is probably acceptable. And if we add a disclaimer along the lines of "development practices are highly dependent upon an individual project's needs, and out of scope for this guide, but the following tools are used by a number of projects" we aren't treading on anyone's toes.

Having written the above, I have come to the conclusion that saying absolutely nothing on the subject of development practices is doing newcomers a disservice. We can be open that it's outside our scope, while still giving people a starting point. If a group like the testing community doesn't like the one-sentence summary we provide, I'm sure we would be more than happy to replace it with a link to their best practices guide, after all!

[cjerdonek]

Right, if we were going to recommend anything, Sphinx+ReadTheDocs is actually the easiest option in most cases.

Hmm, then I'm even more unsure why PyPI is recommending pythonhosted.org. Here is a link to the PyPI source code where it's mentioned. It seems like anything recommended by PyPI should be recommended in the PyPUG, since both are managed by PyPA. And anyone following the tutorial for uploading a package will eventually see those instructions.

[dstufft]

The recommendation in PyPI I think came long before PyPA had any control over PyPI and long before RTD was a thing. At one point someone proposed getting rid of pythonhosted.org and just directing people to RTD but some folks didn't like that because pythonhosted.org allows upload of arbitrary html and isn't tied to Sphinx.

[dstufft]

To be specific, I don't see any reason why the recommendation can't change.

[cjerdonek]

@dstufft Okay, if the functionality on PyPI will remain there, then I think it would help if the language on PyPI were changed so it's clear that pythonhosted.org isn't the new "latest and greatest" way (or even the preferred way).

It currently reads, "You can now host documentation at http://pythonhosted.org/..." From reading that, I got the impression that it was a new go-forward feature as part of your Warehouse work, etc.

On the PyPUG side, the upload section of the tutorial for packagers can recommend that people ignore that form field.

[cjerdonek]

Okay, I proposed a PR for this issue based on @dstufft's answer: https://github.com/pypa/python-packaging-user-guide/issues/112

[ncoghlan]

Following up on some old issues... regarding cookiecutter et al, I just closed #142 on the grounds of project templating tools being out of scope for PyPA. We can't realistically cram an entire development education into a packaging guide, so I think it's reasonable to apply the rule of thumb that if a particular tool would be off-topic for distutils-sig, then it's also off-topic for the packaging guide.

For docs building and hosting though, I think that is on-topic, and there's some further discussion on that in #101 regarding at least mentioning Sphinx.

[brainwane]

pypa/warehouse#582 is where some current progress on this is happening.

[webknjaz]

Does this need to remain open still?