The link explaining python's requirements files was formatted
incorrectly (missing underscore at the end). This resulted in the text
being rendered literally, as opposed to being converted into a
hyperlink.

CONTRIBUTING.rst: Fix formatting of link to pip docs

See merge request !1094

This commit also ensures that if we try to use the 'old' commands,
BuildStream will fail and instruct the user to use the new command.

'artifact checkout' has slightly different behaviour from 'checkout',
that is, either '--directory' or '--tar' are now required options.
This is a step towards allowing checkout to take multiple args.

This commit marks 'bst checkout' as a 'hidden' command. If used,
the user will be prompted to use the new 'bst artifact checkout'
command.

All tests which used 'bst checkout' have been modified to use
the new artifact sub-command.

This partially solves #822.

Due to an upstream click_man issue:
https://github.com/click-contrib/click-man/issues/10
generating the man pages with our current setup.py only generates
a man page for bst-artifact-server, our first entry point.
I then had to remove this entry point from setup.py and regenerate to
obtain man pages for the commands in cli.py

Move push/pull/checkout to the artifact subcommand group

See merge request !1045

Click 7.0 allows us to declare commands as 'hidden'.
However, sphinx-click and click-man still generate these hidden
commands in the documentation and man pages, respectively.

This is a stop gap solution until the upstream issues (tracked in
issues #879 and #881) have been addressed.

Add an obsoletion note to our deprecated commands.

See merge request !1097

Chandan Singh authored Jan 21, 2019 and Chandan Singh committed Jan 22, 2019

https://github.com/rtfd/sphinx_rtd_theme/pull/672 has been fixed
upstream, and the newer versions of `sphinx_rtd_theme` do not break
search functionality with Sphinx >= 1.8.