docs: make readthedocs render a bit nicer and port docs over to Sphinx (#1511)

This makes the Sphinx-based docs hosted on readthedocs render a bit more
nicely, fixes a few issues, and adds some features to //sphinxdocs

This also moves all the docs onto Sphinx, deleting the checked-in
documentation.

Doc fixes/improvements:
* Ports various docs over to Sphinx pages. They're split out from the
readme file.
* Version RTD is building is reflected in the docs
* Fixes some references to github files
* Includes the custom CSS file that styled the api docs
* Removes `-Q` from doc building; all warnings should be fixed now
* Added Bazel inventory file. Bazel doesn't provide one, but we can
manually provide on
  and still use intersphinx functionality.
* Added `gh-path` custom role. This is a shortcut for writing the whole
github URL.
* Sets the primary domain to None. The default is py, which we don't use
much of, so it
  just results in confusing crossref errors.
* Enable nitpicky mode to catch more errors.
* Remove the `starlark` marker from codeblocks; that name isn't
recognized by Sphinx.
  The highlighting is still sufficient.
* Adds a glossary

Sphinxdocs improvements:
* Added a flag to pass along arbitrary `-D` args to the Sphinx
invocations. This allows
e.g., the `version` setting of the docs to be set on the command line
from the
  `READTHEDOCS_VERSION` environment variable
* Added inventory file generation. These are files that allow
referencing external
  projects using intersphinx.
* `sphinx_stardocs` have their public load path set as their page title.
This groups the
  API docs more naturally by file. The path can be customized.
* `sphinx_stardocs` can have a footer specified for generated pages.
This allows easily
  added a list of link labels for easy re-use.
* `readthedocs_install` now tries harder to find an open port
* The conf.py file is moved into the generated sources directly. This
was done because some
config settings are relative to the conf.py file, which was being placed
one directory
  above the regular sources.

Fixes #1484, #1481

1 files changed, 85 insertions, 0 deletions

diff --git a/docs/sphinx/pip.md b/docs/sphinx/pip.md
new file mode 100644
index 0000000..180d0b4
--- /dev/null
+++ b/docs/sphinx/pip.md
@@ -0,0 +1,85 @@
+(pip-integration)=
+# Pip Integration
+
+To pull in dependencies from PyPI, the `pip_parse` macro is used.
+
+
+This macro wraps the [`pip_repository`](./pip_repository.md) rule that invokes `pip`.
+In your WORKSPACE file:
+
+```starlark
+load("@rules_python//python:pip.bzl", "pip_parse")
+
+pip_parse(
+    name = "pip_deps",
+    requirements_lock = ":requirements.txt",
+)
+
+load("@pip_deps//:requirements.bzl", "install_deps")
+
+install_deps()
+```
+
+You can then reference installed dependencies from a `BUILD` file with:
+
+```starlark
+load("@pip_deps//:requirements.bzl", "requirement")
+
+py_library(
+    name = "bar",
+    ...
+    deps = [
+        "//my/other:dep",
+        requirement("requests"),
+        requirement("numpy"),
+    ],
+)
+```
+
+In addition to the `requirement` macro, which is used to access the generated `py_library`
+target generated from a package's wheel, The generated `requirements.bzl` file contains
+functionality for exposing [entry points][whl_ep] as `py_binary` targets as well.
+
+[whl_ep]: https://packaging.python.org/specifications/entry-points/
+
+```starlark
+load("@pip_deps//:requirements.bzl", "entry_point")
+
+alias(
+    name = "pip-compile",
+    actual = entry_point(
+        pkg = "pip-tools",
+        script = "pip-compile",
+    ),
+)
+```
+
+Note that for packages whose name and script are the same, only the name of the package
+is needed when calling the `entry_point` macro.
+
+```starlark
+load("@pip_deps//:requirements.bzl", "entry_point")
+
+alias(
+    name = "flake8",
+    actual = entry_point("flake8"),
+)
+```
+
+(vendoring-requirements)=
+## Vendoring the requirements.bzl file
+
+In some cases you may not want to generate the requirements.bzl file as a repository rule
+while Bazel is fetching dependencies. For example, if you produce a reusable Bazel module
+such as a ruleset, you may want to include the requirements.bzl file rather than make your users
+install the WORKSPACE setup to generate it.
+See https://github.com/bazelbuild/rules_python/issues/608
+
+This is the same workflow as Gazelle, which creates `go_repository` rules with
+[`update-repos`](https://github.com/bazelbuild/bazel-gazelle#update-repos)
+
+To do this, use the "write to source file" pattern documented in
+https://blog.aspect.dev/bazel-can-write-to-the-source-folder
+to put a copy of the generated requirements.bzl into your project.
+Then load the requirements.bzl file directly rather than from the generated repository.
+See the example in rules_python/examples/pip_parse_vendored.