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
merged 22 commits into from May 15, 2020
Merged

doc overhaul step 3: update userguide #2111

merged 22 commits into from May 15, 2020

Conversation

alvyjudy
Copy link
Contributor

@alvyjudy alvyjudy commented May 14, 2020

#2093

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

docs/userguide/
    index.txt
    quickstart.txt
    package_discovery.txt
    entry_point.txt
    dependency_management.txt
    datafiles.txt
    development_mode.txt
    distribution.txt
    extension.txt
    declarative_config.txt
    keywords.txt
    commands.txt

Example section in quickstart.txt

image

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
@jaraco
Copy link
Member

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
@alvyjudy
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
Member

@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
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants