Fix //docs:update (#876)

Fix //docs:update

Also regenerates docs with the new stardoc version.

Right now the command errors out on fresh clones or after a `bazel
clean`.

    $ bazel run //docs:update
    cp: cannot stat 'bazel-bin/docs/packaging.md_': No such file or directory
    cp: cannot stat 'bazel-bin/docs/pip.md_': No such file or directory
    cp: cannot stat 'bazel-bin/docs/pip_repository.md_': No such file or directory
    cp: cannot stat 'bazel-bin/docs/python.md_': No such file or directory

I submitted bazelbuild/stardoc#139 to fix this. @brandjon pointed out
that this should just work as-is, but doesn't because of
bazelbuild/bazel#15043. Until the bazel bug is addressed, we can make
`//docs:update` work by pulling in the latest stardoc version.

One side effect of this patch is that the generated documentation
itself changed a decent amount.

Now the tool works again without errors even after a fresh clone or a
`bazel clean`

    $ bazel run //docs:update
    'bazel-bin/docs/packaging.md_' -> 'docs/packaging.md'
    'bazel-bin/docs/pip.md_' -> 'docs/pip.md'
    'bazel-bin/docs/pip_repository.md_' -> 'docs/pip_repository.md'
    'bazel-bin/docs/python.md_' -> 'docs/python.md'

1 files changed, 36 insertions, 32 deletions

diff --git a/docs/python.md b/docs/python.md
index bd14b82..1726ade 100755
--- a/docs/python.md
+++ b/docs/python.md
@@ -1,6 +1,10 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
-<a name="#current_py_toolchain"></a>
+
+Core rules for building Python projects.
+
+
+<a id="current_py_toolchain"></a>
 
 ## current_py_toolchain
 
@@ -19,11 +23,11 @@ current_py_toolchain(<a href="#current_py_toolchain-name">name</a>)
 
 
 | Name  | Description | Type | Mandatory | Default |
-| :-------------: | :-------------: | :-------------: | :-------------: | :-------------: |
-| name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="current_py_toolchain-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
 
 
-<a name="#py_import"></a>
+<a id="py_import"></a>
 
 ## py_import
 
@@ -45,13 +49,13 @@ This rule allows the use of Python packages as dependencies.
 
 
 | Name  | Description | Type | Mandatory | Default |
-| :-------------: | :-------------: | :-------------: | :-------------: | :-------------: |
-| name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
-| deps |  The list of other libraries to be linked in to the binary target.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-| srcs |  The list of Python package files provided to Python targets that depend on this target. Note that currently only the .egg format is accepted. For .whl files, try the whl_library rule. We accept contributions to extend py_import to handle .whl.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="py_import-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="py_import-deps"></a>deps |  The list of other libraries to be linked in to the binary target.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
+| <a id="py_import-srcs"></a>srcs |  The list of Python package files provided to Python targets that depend on this target. Note that currently only the .egg format is accepted. For .whl files, try the whl_library rule. We accept contributions to extend py_import to handle .whl.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
 
 
-<a name="#py_runtime_pair"></a>
+<a id="py_runtime_pair"></a>
 
 ## py_runtime_pair
 
@@ -74,8 +78,8 @@ schema:
 
 ```python
 platform_common.ToolchainInfo(
-    py2_runtime = <PyRuntimeInfo or None>,
-    py3_runtime = <PyRuntimeInfo or None>,
+    py2_runtime = &lt;PyRuntimeInfo or None&gt;,
+    py3_runtime = &lt;PyRuntimeInfo or None&gt;,
 )
 ```
 
@@ -106,7 +110,7 @@ py_runtime_pair(
 
 toolchain(
     name = "my_toolchain",
-    target_compatible_with = <...>,
+    target_compatible_with = &lt;...&gt;,
     toolchain = ":my_py_runtime_pair",
     toolchain_type = "@rules_python//python:toolchain_type",
 )
@@ -123,13 +127,13 @@ register_toolchains("//my_pkg:my_toolchain")
 
 
 | Name  | Description | Type | Mandatory | Default |
-| :-------------: | :-------------: | :-------------: | :-------------: | :-------------: |
-| name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
-| py2_runtime |  The runtime to use for Python 2 targets. Must have <code>python_version</code> set to <code>PY2</code>.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
-| py3_runtime |  The runtime to use for Python 3 targets. Must have <code>python_version</code> set to <code>PY3</code>.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="py_runtime_pair-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="py_runtime_pair-py2_runtime"></a>py2_runtime |  The runtime to use for Python 2 targets. Must have <code>python_version</code> set to <code>PY2</code>.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
+| <a id="py_runtime_pair-py3_runtime"></a>py3_runtime |  The runtime to use for Python 3 targets. Must have <code>python_version</code> set to <code>PY3</code>.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
 
 
-<a name="#py_binary"></a>
+<a id="py_binary"></a>
 
 ## py_binary
 
@@ -143,11 +147,11 @@ See the Bazel core [py_binary](https://docs.bazel.build/versions/master/be/pytho
 
 
 | Name  | Description | Default Value |
-| :-------------: | :-------------: | :-------------: |
-| attrs |  Rule attributes   |  none |
+| :------------- | :------------- | :------------- |
+| <a id="py_binary-attrs"></a>attrs |  Rule attributes   |  none |
 
 
-<a name="#py_library"></a>
+<a id="py_library"></a>
 
 ## py_library
 
@@ -161,11 +165,11 @@ See the Bazel core [py_library](https://docs.bazel.build/versions/master/be/pyth
 
 
 | Name  | Description | Default Value |
-| :-------------: | :-------------: | :-------------: |
-| attrs |  Rule attributes   |  none |
+| :------------- | :------------- | :------------- |
+| <a id="py_library-attrs"></a>attrs |  Rule attributes   |  none |
 
 
-<a name="#py_runtime"></a>
+<a id="py_runtime"></a>
 
 ## py_runtime
 
@@ -179,11 +183,11 @@ See the Bazel core [py_runtime](https://docs.bazel.build/versions/master/be/pyth
 
 
 | Name  | Description | Default Value |
-| :-------------: | :-------------: | :-------------: |
-| attrs |  Rule attributes   |  none |
+| :------------- | :------------- | :------------- |
+| <a id="py_runtime-attrs"></a>attrs |  Rule attributes   |  none |
 
 
-<a name="#py_test"></a>
+<a id="py_test"></a>
 
 ## py_test
 
@@ -197,11 +201,11 @@ See the Bazel core [py_test](https://docs.bazel.build/versions/master/be/python.
 
 
 | Name  | Description | Default Value |
-| :-------------: | :-------------: | :-------------: |
-| attrs |  Rule attributes   |  none |
+| :------------- | :------------- | :------------- |
+| <a id="py_test-attrs"></a>attrs |  Rule attributes   |  none |
 
 
-<a name="#find_requirements"></a>
+<a id="find_requirements"></a>
 
 ## find_requirements
 
@@ -218,7 +222,7 @@ The aspect definition. Can be invoked on the command line as
 
 
 | Name | Type |
-| :-------------: | :-------------: |
+| :------------- | :------------- |
 | deps| String |
 
 
@@ -226,7 +230,7 @@ The aspect definition. Can be invoked on the command line as
 
 
 | Name  | Description | Type | Mandatory | Default |
-| :-------------: | :-------------: | :-------------: | :-------------: | :-------------: |
-| name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |   |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="find_requirements-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |   |