Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Creating documentation #568
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.