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
merged 4 commits into from Nov 5, 2018

Conversation

@elainechan
Copy link
Contributor

elainechan commented Oct 29, 2018

Responding to Issue #484

@theacodes

This comment has been minimized.

Copy link
Member

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?

@elainechan

This comment has been minimized.

Copy link
Contributor Author

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
1 check passed
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@theacodes

This comment has been minimized.

Copy link
Member

theacodes commented Nov 5, 2018

Thanks, @elainechan!

@ben-spiller

This comment has been minimized.

Copy link

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 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.