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

doc overhaul step 3: update userguide #2111

merged 22 commits into from May 15, 2020

doc overhaul step 3: update userguide #2111

merged 22 commits into from May 15, 2020


Copy link

@alvyjudy alvyjudy commented May 14, 2020


Summary of changes

The userguide (originally the setuptools.txt document) is now one step closer to reader-friendliness. It is comprised of three parts:

  • an index that provide an introduction and roadmap
  • a quickstart that provide guidance (minimal knowledge) on the commonly used functionalities (e.g. entry point, automatic package discovery, package dependencies, etc.), each accompanied with a link to a dedicated file for advance use and technical details
  • multiple dedicated files for each section introduced in quickstart and other less commonly used tools

Again, most edits were still cut-and-paste (so the content still assumes the traditional usage. It might still take a while before some real edits can take place.

Pull Request Checklist

  • Changes have tests
  • News fragment added in changelog.d. See documentation for details

The userguide directory layout


Example section in quickstart.txt


alvyjudy added 22 commits May 13, 2020
from quickstart.txt to functionalities.txt
so that the quickstart is cleaner for now. Might add more text later
egg-secutable section moved from userguide/functionalities to deprecated/functionalities
such that each section is comprised of a quick intro and example
that illustrate the use of that functionality and provide a link
to a more detailed explanation.
outline is completed, now to fill the donut holes
those that don't need to put into a dedicated file
are now inside the miscellaneous.txt
these should be properly grouped but for now I'm just
leaving them here
Copy link

jaraco commented May 15, 2020

There's a lot going on here. I'm going to accept this without reviewing it thoroughly.

Don't feel obliged to create a changelog for each PR. An end-user is not going to care that there were multiple phases of a doc overhaul. I'll likely consolidate these when we get around to merging the changes.

In #1738, some substantial changes were made to the docs. I hope those don't cause difficulty in conflicts. Please try to incorporate those changes into yours.

@jaraco jaraco merged commit c1a36a3 into pypa:feature/2093-docs-revamp May 15, 2020
1 of 3 checks passed
Copy link
Contributor Author

alvyjudy commented May 15, 2020

Sure thing I'll do that. Thanks for the advice

@alvyjudy alvyjudy deleted the doc branch May 15, 2020
like, and each one can optionally specify "extras" that it depends on, that
will be added to ``sys.path`` when the script is run. For more information on
"extras", see the section below on `Declaring Extras`_. For more information
on "entry points" in general, see the section below on `Dynamic Discovery of
Copy link

@webknjaz webknjaz Oct 15, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alvyjudy I noticed you use a hyperlink syntax for refs. It doesn't work like that.
For refs, you have to create labels and then use :ref: role to link those...

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