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

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

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
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
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

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 pradyunsg moved this from To do to In progress in Documentation improvements Mar 21, 2021
@pradyunsg pradyunsg removed this from In progress in Documentation improvements Mar 21, 2021
@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

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

@pradyunsg
Copy link
Member Author

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

@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.

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type: docs Documentation related
Projects
Development

No branches or pull requests

3 participants