Creating documentation

[elainechan]

Responding to Issue #484

[theacodes]

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?

[elainechan]

Added link to Hitchhiker's Guide to Python.

[theacodes]

Thanks, @elainechan!

[ben-spiller]

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.