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.

Sign up for GitHub

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

Jump to bottom

Major changes to the documentation #9475

Open
pradyunsg opened this issue Jan 19, 2021 · 13 comments
Open

Major changes to the documentation #9475

pradyunsg opened this issue Jan 19, 2021 · 13 comments
Labels
type: docs Documentation related

Comments

@pradyunsg
Copy link
Member

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. :)
@pradyunsg pradyunsg added the type: docs Documentation related label Jan 19, 2021
@pradyunsg
Copy link
Member Author

pradyunsg commented Jan 19, 2021 •
edited
Loading

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.

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

@pradyunsg pradyunsg mentioned this issue Jan 19, 2021
Closed
@pradyunsg
Copy link
Member Author

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.

@pradyunsg
Copy link
Member Author

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

@pradyunsg
Copy link
Member Author

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)

@pradyunsg pradyunsg mentioned this issue Mar 6, 2021
Merged
@pradyunsg
Copy link
Member Author

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 readthedocs/readthedocs.org#4221.

@pradyunsg
Copy link
Member Author

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

@cjc7373
Copy link
Contributor

cjc7373 commented Mar 8, 2021

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

@pradyunsg
Copy link
Member Author

pradyunsg commented Mar 8, 2021 •
edited
Loading

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

@pradyunsg
Copy link
Member Author

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

@pradyunsg
Copy link
Member Author

pradyunsg commented Mar 21, 2021 •
edited
Loading

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

This was referenced Mar 21, 2021
Merged
Merged
@pradyunsg
Copy link
Member Author

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

@pradyunsg pradyunsg mentioned this issue May 21, 2021
Merged
This was referenced May 28, 2021
Merged
Merged
Merged
@pradyunsg
Copy link
Member Author

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.

@pradyunsg pradyunsg mentioned this issue May 28, 2021
Merged
This was referenced Jun 11, 2021
Merged
Merged
@pradyunsg pradyunsg mentioned this issue Jun 25, 2021
Merged
This was referenced Jun 25, 2021
Merged
Merged
@bhrutledge bhrutledge mentioned this issue Jul 10, 2021
Merged
@pradyunsg pradyunsg mentioned this issue Jul 13, 2021
Closed
This was referenced Aug 6, 2021
Merged
Merged
This was referenced Sep 8, 2021
Merged
Merged
This was referenced Sep 18, 2021
Merged
Closed
Closed
@benjaoming benjaoming mentioned this issue Sep 18, 2021
Closed
This was referenced Sep 22, 2021
Merged
Closed
@pradyunsg pradyunsg mentioned this issue Oct 1, 2021
Open
@pradyunsg pradyunsg mentioned this issue Jan 26, 2022
Merged
4 tasks
@pradyunsg pradyunsg mentioned this issue Feb 11, 2022
Merged
@pradyunsg pradyunsg mentioned this issue Mar 11, 2022
Merged
@SnoopJ
Copy link
Contributor

SnoopJ commented Jul 14, 2022

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 xonsh/xonsh#4878) asking for an authoritative guide about the dangers.

This was referenced Jul 29, 2022
Merged
Merged
Merged
@pradyunsg pradyunsg mentioned this issue Aug 26, 2022
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
type: docs Documentation related
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@pradyunsg @SnoopJ @cjc7373