Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Creating documentation #568

merged 4 commits into from Nov 5, 2018


Copy link

@elainechan elainechan commented Oct 29, 2018

Responding to Issue #484

Copy link

@theacodes theacodes commented Oct 31, 2018

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?

Copy link
Contributor Author

@elainechan elainechan commented Nov 3, 2018

Added link to Hitchhiker's Guide to Python.

@theacodes theacodes merged commit 46708a6 into pypa:master Nov 5, 2018
1 check passed
Copy link

@theacodes theacodes commented Nov 5, 2018

Thanks, @elainechan!

Copy link

@ben-spiller ben-spiller commented Feb 19, 2019

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 which suggests to add "include docs/*.txt" in your 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
None yet

Successfully merging this pull request may close these issues.

None yet

3 participants