This is basically the supporting issue to #9474, with the idea being to have any broad overarching discussions over here, with code review happening in that PR. :)

Jan 19 '21 23:01 pradyunsg

So... I started a rewrite of pip's documentation. I'm obviously not done yet, but it's up as a draft very-much-in-progress PR now. I'd like to get feedback on stuff I've done so far, to see if folks do like the general direction this is going. :)

Broadly, the ideas here are:

Move to Markdown (MyST) for almost all pages.
Reorganise existing information, to be more... accessible and discoverable.
Breakup "everything in one page" into multiple "single topic" pages.
- Rewrite certain sentences, so that there's a consistent style -- mine. :P
Restructure the entire thing, to organise information in more sensible groups.
- We're not doing https://documentation.divio.com/ style split-the-4-kinds -- because... I ain't writing new tutorials and how-to guides.

There are 2 "new" pages I want to add (i.e. new content that didn't previously exist), based on documentation feedback from our user research:

FAQ
Common Errors

Jan 19 '21 23:01 pradyunsg

The preview for the draft PR of the rewrite is up at https://pip--9474.org.readthedocs.build/en/9474/. As usual, feedback is welcome. :)

/cc @brainwane @nlhkabu @pypa/pip-committers since I'd really like to hear from them.

Jan 19 '21 23:01 pradyunsg

Oh yea, and the plan for migration is... to preserve/re-add the old hierarchy as "orphan" pages and add links to the moved content.

And then give search engines ~3-6 months to update to the new locations. We can probably also add RTD redirects at some point, but I'm a little uncomfortable since those aren't surfaced in a config file or whatever. And I don't imagine that being being priority for RTD, since, uhm, it's a team that's stretched really thin already. :)

Jan 19 '21 23:01 pradyunsg

Dumping a bunch of stackoverflow links, that have either really bad answers or a lot of traffic.

FAQ

https://stackoverflow.com/questions/21055859/what-are-the-risks-of-running-sudo-pip https://stackoverflow.com/questions/5226311/installing-specific-package-versions-with-pip https://stackoverflow.com/questions/7225900/how-to-install-packages-using-pip-according-to-the-requirements-txt-file-from-a https://stackoverflow.com/questions/739993/how-can-i-get-a-list-of-locally-installed-python-modules https://stackoverflow.com/questions/3220404/why-use-pip-over-easy-install https://stackoverflow.com/questions/11248073/what-is-the-easiest-way-to-remove-all-packages-installed-by-pip https://stackoverflow.com/questions/4888027/python-and-pip-list-all-versions-of-a-package-thats-available https://stackoverflow.com/questions/9510474/removing-pips-cache

Common Errors

https://stackoverflow.com/questions/2817869/error-unable-to-find-vcvarsall-bat https://stackoverflow.com/questions/8548030/why-does-pip-install-inside-python-raise-a-syntaxerror https://stackoverflow.com/questions/23708898/pip-is-not-recognized-as-an-internal-or-external-command https://stackoverflow.com/questions/49768770/not-able-to-install-python-packages-ssl-tlsv1-alert-protocol-version https://stackoverflow.com/questions/31512422/pip-install-failing-with-oserror-errno-13-permission-denied-on-directory https://stackoverflow.com/questions/25981703/pip-install-fails-with-connection-error-ssl-certificate-verify-failed-certi https://stackoverflow.com/questions/35991403/pip-install-unroll-python-setup-py-egg-info-failed-with-error-code-1 https://stackoverflow.com/questions/49748063/pip-install-fails-for-every-package-could-not-find-a-version-that-satisfies https://stackoverflow.com/questions/52460484/python-3-5-pip-9-attributeerror-nonetype-object-has-no-attribute-bytes

(also, https://pip.pypa.io/en/stable/user_guide/#fixing-conflicting-dependencies moves into one of these)

Mar 02 '21 10:03 pradyunsg

add RTD redirects at some point, but I'm a little uncomfortable since those aren't surfaced in a config file or whatever

I think there's basically only one class of redirects we'd need to configure here -- reference -> cli stuff:

/reference/pip_cache/ -> /cli/pip_cache/
/reference/pip_check/ -> /cli/pip_check/
/reference/pip_config/ -> /cli/pip_config/
/reference/pip_debug/ -> /cli/pip_debug/
/reference/pip_download/ -> /cli/pip_download/
/reference/pip_freeze/ -> /cli/pip_freeze/
/reference/pip_hash/ -> /cli/pip_hash/
/reference/pip_install/ -> /cli/pip_install/
/reference/pip_list/ -> /cli/pip_list/
/reference/pip_search/ -> /cli/pip_search/
/reference/pip_show/ -> /cli/pip_show/
/reference/pip_uninstall/ -> /cli/pip_uninstall/
/reference/pip_wheel/ -> /cli/pip_wheel/
/reference/pip/ -> /cli/pip/

And redirecting installation to "Quickstart".

And I don't imagine that being being priority for RTD, since, uhm, it's a team that's stretched really thin already. :)

Yup. See https://github.com/readthedocs/readthedocs.org/issues/4221.

Mar 06 '21 11:03 pradyunsg

Annnd the first PR (#9693) making the necessary non-content changes for this rewrite is filed!

Mar 06 '21 11:03 pradyunsg

Just out of curiosity, why moving from rst to markdown?

Mar 08 '21 16:03 cjc7373

Markdown is a significantly more popular markup format than reStructuredText.

It’s likely that potential contributors who are not professional-Python-developers are fairly familiar with Markdown, but haven't used reStructuredText. MyST gives you the best of both worlds – simplicity and familiarity of Markdown with the extensibility power of reST. It's already in use by the Jupyter Book project and is stable enough to write documentation like (most of) https://pradyunsg.me/furo with it.

Also, I think it's much easier to write, and I'm doing a lot of the writing here. :)

Mar 08 '21 20:03 pradyunsg

I made a GitHub project to track this now, and I'll be updating things there instead of making comments here.

Mar 21 '21 10:03 pradyunsg

Expand to see current documentation hierarchy (warning: long list)

Mar 21 '21 10:03 pradyunsg

Picking this back up now, since I'll have additional capacity!

May 21 '21 12:05 pradyunsg

I've figured out a better name for the "Explanation" section from #9474: Topic Guide

Each page within that section is providing mostly-complete information on that specific topic, to aid understanding and maybe provide guidance on what to do. These pages roughly map to https://diataxis.fr/explanation/ within the Diátaxis Framework.

May 28 '21 12:05 pradyunsg

https://stackoverflow.com/questions/21055859/what-are-the-risks-of-running-sudo-pip

I'm guessing this is something you already have in mind for this issue, but it would be great if the pip user guide included a section dedicated to discussing the fraught nature of sudo pip. I ended up searching for this issue when responding to a user question (related to https://github.com/xonsh/xonsh/issues/4878) asking for an authoritative guide about the dangers.

Jul 14 '22 18:07 SnoopJ

pip
pip copied to clipboard

Major changes to the documentation

FAQ

Common Errors

pip pip copied to clipboard

Major changes to the documentation

FAQ

Common Errors

pip
pip copied to clipboard