Add resolver docs

[nlhkabu]

Closes #8459

TODO:

• Build and preview
• Add NEWS

[pfmoore]

I'm not enough of a ReST expert to comment on the markup, but the content looks good to me.

[pradyunsg]

@nlhkabu Pull Requests on pip's tracker automatically get their documentation built + made available for preview. It's a check called "docs/readthedocs.org:pip" in the list of checks on the PR, and "details" link on it, points to the preview.

The section added in this PR is available at: https://pip--8493.org.readthedocs.build/en/8493/user_guide/#fixing-conflicting-dependencies

Any changes made on this PR will also get reflected on that page. :)

[pfmoore]

TIL! :-)

[brainwane]

This is a great document -- thank you for putting it together! I like the structure and the content and the clear writing with concrete examples.

[deveshks]

Hi @nlhkabu

Just as a suggestion, you can also add multiple review suggestions to a batch, and apply all of them under a single commit, instead of one commit per suggestion.

This is also described in the 2nd sub point of the 3rd point at https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request

To add the suggestion to a batch of changes, click Add suggestion to batch. 
Continue to add the suggested changes you want to include in a single commit.
When you've finished adding suggested changes, click Commit suggestions.

[nlhkabu]

Hi @deveshks - yes, I saw that, but unfortunately the "Add suggestion to batch" button was disabled on GitHub. Not sure if it has something to do with my permissions on this project.

I will squash the commits to clean up the commit history before finalising the PR.

[pradyunsg]

@nlhkabu for batch suggestions, you need to go into the files view. (the disabled button in the other view has a tooltip indicating this)

[pradyunsg]

I think this is good to go. Let's go ahead and merge this now -- we can iterate on this in the future as needed.

To that end, @nlhkabu could you please rebase this on master (to resolver the Travis CI failures) and add a news/8493.doc file containing a changelog entry (to satisfy the news file check)? :)

[nlhkabu]

Yep @pradyunsg just making some edits on my side (both formatting and content). Hope to submit for merge today.

[nlhkabu]

This is now ready for final review: https://pip--8493.org.readthedocs.build/en/8493/user_guide/#fixing-conflicting-dependencies

If we're happy with this, I'll add NEWS and clean up the commit history.

Note: I didn't convert the table to a definition list, as I was not sure where to put the examples in that format.

Thanks!

[pradyunsg]

Happy to merge once a NEWS entry is added! ^>^

[nlhkabu]

@pradyunsg this is ready to go on my side.
Not sure why "experimental" CI is failing?

[McSinyx]

@nlhkabu, the commit you're basing this PR on has them failed to. I'm not sure if that's necessary, but to get rid of the red cross you can rebase it on current master which is green.

[pradyunsg]

@McSinyx's analysis is correct, but the failing checks aren't a blocker for merging this PR. I can merge it once I'm on my PC (GitHub doesn't let me merge from a mobile device if any CI check fails).

[nlhkabu]

ping @pradyunsg for merge :)

[pradyunsg]

Thanks for the ping @nlhkabu! ^>^