Thanks for doing this, it's a good start but it seems really barebones. Are there other resources we can point users to for using Sphinx to document their project? Maybe the hitchhiker's guide to Python?

Added link to Hitchhiker's Guide to Python.

Thanks, @elainechan!

It's a great start but there's one really key aspect that's not yet clear, which is how to distribute the generated docs? Firstly are we encouraged/discouraged from including docs (whether html or rst/txt/md) in binary .whl distributions so they're available locally in the installation, or only to put them onto the web?

And for people who do wish to include html/text documentation files in their whl, how to do it? There is only one reference to packaging documentation in the main guide at https://python-packaging.readthedocs.io/en/latest/non-code-files.html which suggests to add "include docs/*.txt" in your MANIFEST.in file. However this does not work work for the recommended binary .whl distribution mechanism since documentation files obviously (and rightly) are located in a toplevel docs/ directory not inside a package directory where the code is, therefore they do not get included.

It's probably possible to install docs in a .whl in a manual fashion using the non-package data_files option but I believe that's not exactly encouraged (?) and isn't easy (at least without guidance) to figure out how to ensure the docs get installed to a sensible place that's both easy to find and not going to clash with other packages' documentation. A recommended recipe for this would be really helpful for the python community.