Documentation rewrite (Q1 2021) #9474

pradyunsg · 2021-01-19T22:58:20Z

See #9475 for context and the overall idea here.

PS: If you're reviewing this, I'd say, either look at the PR preview or go commit-by-commit. Looking at the total diff will be painful.

pradyunsg · 2021-01-19T23:03:53Z

Oh, and you can probably see this in the RTD preview -- my rough plan for the hierarchy/structure is:

- Getting Started
- Explanations
  # topical descriptions of how stuff works, like Configuration, Authentication etc
  ...
- Reference
  # "raw" information about formats/interfaces that pip defines/how it uses them
  - Requirements Files
  - Constraint Files
  - Build System Interfaces
  # more?
- Commands
  # CLI information -- pure reference stuff with simplified descriptions
  ...
- Project Management
  # for communicating about "how and _why_ we do things" to downstream/end users
  - release
  - deprecation / change management info
  - vendoring
- Changelog

**TROUBLESHOOTING**

- Common Errors
- FAQ

**CONTRIBUTING**

- Development
  # written by pip's maintainers, for pip's contributors
  - Workflow
  - Issues
  - Pull Requests
  - Communication
- Architecture
  # implementation details and stuff
  ...
- Maintainance
  # written by pip's maintainers, for pip's maintainers
  - Change Management
  - Release Management
  - Team
UX research and design
  # UX Recommendations
  # And research summaries/descriptions in a sub-tree of "past research"
  # This will probably become a section, but I'll defer to the experts on this. :)

pypa-bot · 2021-02-04T10:34:58Z

Hello!

I am an automated bot and I have noticed that this pull request is not currently able to be merged. If you are able to either merge the master branch into this pull request or rebase this pull request against master then it will eligible for code review and hopefully merging!

BrownTruck · 2021-02-22T20:32:35Z

Hello!

I am an automated bot and I have noticed that this pull request is not currently able to be merged. If you are able to either merge the master branch into this pull request or rebase this pull request against master then it will be eligible for code review and hopefully merging!

pradyunsg · 2021-02-23T13:15:56Z

@pypa/pip-committers this seems like it's gonna a big PR, so it'd be nice if someone could start reviewing this incrementally, since... There's a lot here and I don't know of any way to do this in smaller chunks.

Ideas for breaking this up into smaller chunks are super welcome. :)

uranusjr · 2021-02-24T10:45:09Z

In the Getting Started page, it’s probably better to

Add a visible block declaring pip only works with Python 3.6+
Rewrite the “pip is already installed if you are” part fo remove “modern” and “>= 3.5” (because that’s implied for all pip installations now)

uranusjr · 2021-02-24T10:46:16Z

Or, if you don’t mind more conflicts, I can just propose them separately to the current documentation 🙂

uranusjr · 2021-02-24T10:52:09Z

docs/html/explanations/authentication.md

+pip supports loading credentials from a user's `.netrc` file. If no credentials
+are part of the URL, pip will attempt to get authentication credentials for the
+URL's hostname from the user's `.netrc` file. This behaviour comes from the
+underlying use of [`requests`][pypi-requests], which in turn delegates it to


This seems broken

Ah yes, I never added the link. :)

This simplifies the Sphinx configuration and adds additional grouping and structure to the existing code as well.

Use eval-rst, for directives that don't support MyST yet.

m-aciek · 2021-03-04T22:58:14Z

Ad. repeatable installs chapter: In my opinion it would be worth to add a note box saying that updating dependency in a "pip frozen" environment can be a pain, because requirements.txt file lacks information which dependency is top-level and which is not. And for such use cases pip-tools and other dependency managers are preferred.

pradyunsg · 2021-03-06T11:04:31Z

I've broken out #9693 from this PR, to make it easier to separate the "scaffolding changes" from the "content changes".

I'm thinking of ways to make it possible for us to incrementally switch between these structures, but more on that in follow up PRs! :)

pradyunsg · 2021-03-06T11:22:28Z

Dumping this here, because I can't think of a better place ATM:

* d661b1411 (documentation-rewrite-1) Move constraint files stuff
* 4a3f1f533 Move compatibility information to getting-started
* 6fa46fd17 Tweak sentence in authentication explainer
* 1df09be3f :newspaper:
* df5a856cb Add dedicated page on how configuration works
* 006c9384a Capitalise all headings
* 2b84b1aa9 Add explanation page for custom install options
* 01f5528bb Add dedicated page for Requirements File format
* 9b1be27f9 Add dedicated page for VCS support
* be1f1e9a0 Add dedicated page for User Installs
* a4e7291d4 Add dedicated page for Requirements Files
* 49c46ff6f Add dedicated page for Repeatable Installs
* ef9e07cf1 Add dedicated page for editable installs
* cb88f77cd Add dedicated page for Configuration
* 6179dfe0c Add dedicated page for Caching
* 3164397d4 Add dedicated page for authentication
* c34ae86eb Change news to Markdown


pick 175b49b20 Add new documentation skeleton
pick cedd33372 Drop the troubleshooting section for new skeleton
pick a44b0cd80 Drop old .rst files overlapping with new skeleton
pick 92766ba7c Rename docs/html/{reference -> cli}
pick 300d4c2f1 Populate the new Getting Started page
pick be0bc7e14 Point to the PyPUG tutorial from quickstart

BrownTruck · 2021-03-06T23:16:15Z

Hello!

I am an automated bot and I have noticed that this pull request is not currently able to be merged. If you are able to either merge the master branch into this pull request or rebase this pull request against master then it will be eligible for code review and hopefully merging!

m-aciek · 2021-02-25T23:20:36Z

docs/html/explanations/repeatable-installs.md

+```
+
+A requirements file, containing pinned package versions can be generated using
+{ref}`pip freeze`. This would not only the top-level packages, but also all of


This sentence lacks a predicate.

pradyunsg · 2021-09-18T09:46:28Z

Closing this out, since this is being broken up into smaller chunks, as part of #9475. :)

pradyunsg added the type: docs Documentation related label Jan 19, 2021

pradyunsg mentioned this pull request Jan 19, 2021

Major changes to the documentation #9475

Open

pradyunsg force-pushed the documentation-rewrite-1 branch from 5805e74 to a4557fe Compare February 4, 2021 10:34

pypa-bot added the needs rebase or merge PR has conflicts with current master label Feb 4, 2021

pradyunsg force-pushed the documentation-rewrite-1 branch from a4557fe to 2f9593f Compare February 21, 2021 13:22

pypa-bot removed the needs rebase or merge PR has conflicts with current master label Feb 21, 2021

pradyunsg force-pushed the documentation-rewrite-1 branch from 2f9593f to 93d35f5 Compare February 21, 2021 13:29

BrownTruck added the needs rebase or merge PR has conflicts with current master label Feb 22, 2021

pradyunsg mentioned this pull request Feb 23, 2021

Add a warning about "dependency confusion" vulnerability #9647

Merged

pradyunsg mentioned this pull request Feb 23, 2021

Improve docs on pinning version numbers #7820

Closed

uranusjr reviewed Feb 24, 2021

View reviewed changes

pradyunsg added 13 commits February 28, 2021 13:09

Enable MyST in documentation

5a2de5b

Remove the docs-feedback extension

0998b3d

Add new documentation skeleton

ac2c98a

Drop old .rst files overlapping with new skeleton

7b1b87c

Rewrite docs/conf.py

c61ebed

This simplifies the Sphinx configuration and adds additional grouping and structure to the existing code as well.

Add configuration for MyST

4915115

Add .md files in docs/ to MANIFEST

54e20ef

Add autodoc and todo plugins for Sphinx

09ee251

Move CLI docs into cli/ and write new index page

79614e3

Change news to Markdown

3c3967c

Use eval-rst, for directives that don't support MyST yet.

Add sphinx-copybutton

3d159ca

Populate the new Getting Started page

f57c248

Point to the PyPUG tutorial from quickstart

f808256

pradyunsg added 10 commits February 28, 2021 13:09

Add dedicated page for Repeatable Installs

e0693a7

Add dedicated page for Requirements Files

de0d794

Add dedicated page for User Installs

e899320

Add dedicated page for VCS support

001fb46

Add dedicated page for Requirements File format

b8fa4b9

Add a docs-live nox session

4e400ee

Add explanation page for custom install options

01305a5

Capitalise all headings

4b0712e

Add dedicated page on how configuration works

96cbeaf

📰

a339fb1

pradyunsg mentioned this pull request Feb 28, 2021

Blacken docs directory #9671

Closed

pradyunsg force-pushed the documentation-rewrite-1 branch from 76918a4 to a339fb1 Compare March 3, 2021 20:51

pypa-bot removed the needs rebase or merge PR has conflicts with current master label Mar 3, 2021

pradyunsg added 2 commits March 3, 2021 20:51

Tweak sentence in authentication explainer

7c3af23

Move compatibility information to getting-started

8b4d927

pradyunsg mentioned this pull request Mar 6, 2021

Prepare for documentation rewrite #9693

Merged

BrownTruck added the needs rebase or merge PR has conflicts with current master label Mar 6, 2021

pradyunsg mentioned this pull request May 21, 2021

Rewrite the Getting Started and Installation Pages #10009

Merged

m-aciek reviewed May 24, 2021

View reviewed changes

This was referenced Jun 9, 2021

Enable the wiki #10048

Closed

Fix a few trivial mistakes in documentation #10051

Merged

pradyunsg closed this Sep 18, 2021

github-actions bot locked as resolved and limited conversation to collaborators Oct 4, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation rewrite (Q1 2021) #9474

Documentation rewrite (Q1 2021) #9474

pradyunsg commented Jan 19, 2021 •

edited

Loading

pradyunsg commented Jan 19, 2021

pypa-bot commented Feb 4, 2021

BrownTruck commented Feb 22, 2021

pradyunsg commented Feb 23, 2021

uranusjr commented Feb 24, 2021

uranusjr commented Feb 24, 2021

uranusjr Feb 24, 2021 •

edited

Loading

pradyunsg Feb 24, 2021

m-aciek commented Mar 4, 2021

pradyunsg commented Mar 6, 2021

pradyunsg commented Mar 6, 2021 •

edited

Loading

BrownTruck commented Mar 6, 2021

m-aciek Feb 25, 2021

pradyunsg commented Sep 18, 2021

Documentation rewrite (Q1 2021) #9474

Documentation rewrite (Q1 2021) #9474

Conversation

pradyunsg commented Jan 19, 2021 • edited Loading

pradyunsg commented Jan 19, 2021

pypa-bot commented Feb 4, 2021

BrownTruck commented Feb 22, 2021

pradyunsg commented Feb 23, 2021

uranusjr commented Feb 24, 2021

uranusjr commented Feb 24, 2021

uranusjr Feb 24, 2021 • edited Loading

Choose a reason for hiding this comment

pradyunsg Feb 24, 2021

Choose a reason for hiding this comment

m-aciek commented Mar 4, 2021

pradyunsg commented Mar 6, 2021

pradyunsg commented Mar 6, 2021 • edited Loading

BrownTruck commented Mar 6, 2021

m-aciek Feb 25, 2021

Choose a reason for hiding this comment

pradyunsg commented Sep 18, 2021

pradyunsg commented Jan 19, 2021 •

edited

Loading

uranusjr Feb 24, 2021 •

edited

Loading

pradyunsg commented Mar 6, 2021 •

edited

Loading