Improve pip download documentation

[xavfernandez]

It is currently very light and some parts (most of its options) could certainly be factorized with pip wheel and pip install.

[pradyunsg]

This issue is a good starting point for anyone who wants to help out with pip's development -- it's simple and the process of fixing this should be a good introduction to pip's development workflow. :)

[pradyunsg]

Dropping this from the 18.0 release but this is still something we'd like to have.

[brainwane]

@pradyunsg I presume the documentation that needs expanding here is https://pip.pypa.io/en/stable/reference/pip_download/ ?

[satyajitdam]

I'm looking at https://pip.pypa.io/en/stable/reference/pip_download/ and there's quite a bit of documentation there. Is there a certain sections that the missing in the doc or need embellishment?

[elainechan]

Looking at working on this issue. If anyone is currently actively working on this, please comment and I will work on something else.

[elainechan]

Will put a hold on this until after clarification.

[elainechan]

Working together with @satyajitdam on this issue

[pradyunsg]

@sumanah Yes.

The docs directory is the one containing the relavent details.

[brainwane]

Here's what I have gathered:

docs/html/reference/pip_download.rst is the document that gets rendered as https://pip.pypa.io/en/stable/reference/pip_download/ , and it draws some of its content from src/pip/_internal/commands/download.py.

To solve this issue, we need to review the existing documentation in src/pip/_internal/commands/ and look at https://packaging.python.org/tutorials/installing-packages/ to see whether there's any duplication, and then address that.

I believe a more experienced developer needs to do that -- this is, in my opinion, not a good issue for a first-time contributor.

[pradyunsg]

Hmm... Indeed. I had misjudged the complexity of this issue perhaps. There’s definitely more context needed than a first time contributor would have.

Apologies for that.

[elainechan]

@satyajitdam and I have stopped working on this issue.

[gutsytechster]

If the same option is available to multiple commands but not all commands, shouldn't that then be documented for each command seperately?

[brainwane]

@gutsytechster Could you rephrase, maybe with a concrete example? I think you are setting up two choices and asking for a decision between them, but I'm having a little bit of a hard time understanding what those choices are. Thanks!

[gutsytechster]

@brainwane sure!

The issue says that a lot of options described for pip download can be refactored with options with pip wheel or pip install.

However, when a person would go to the pip download's documentation, s/he would look for all the available options. So, shouldn't these options be available for each command's doc individually?

Apart from that, if you'd compare, the documentation of pip wheeland pip install, there are options between them which exist for each documentation page separately. To list a few of them - --no-clean, --pre, --build, etc.

So, what I feel that current documentation for pip download looks good to me(after looking for other command's doc).

[pradyunsg]

I've reviewed this today, as part of working on #9475, and this looks good to me! I don't think factoring out common options is particularly useful; and any additional information/explanations should likely end up in one of the dedicated pages we're building for the concepts as part of #9475.