Improve docs

Author: aignas

BZLMOD_SUPPORT.md

@@ -51,9 +51,10 @@ the toolchains rules_python registers**.
 NOTE: Regardless of your toolchain, due to
 [#691](https://github.com/bazelbuild/rules_python/issues/691), `rules_python`
 still relies on a local Python being available to bootstrap the program before
-handing over execution to the toolchain Python. To override this behaviour see
-{obj}`--bootstrap_impl=script`, which switches to `bash`-based bootstrap on
-UNIX systems.
+handing over execution to the toolchain Python.
+
+To override this behaviour see {obj}`--bootstrap_impl=script`, which switches
+to `bash`-based bootstrap on UNIX systems.
 
 ### Better PyPI package downloading on bzlmod
 

docs/getting-started.md

@@ -1,7 +1,7 @@
 # Getting started
 
 This doc is a simplified guide to help get started started quickly. It provides
-a simplified introduction to having a working Python program for both bzlmod
+a simplified introduction to having a working Python program for both `bzlmod`
 and the older way of using `WORKSPACE`.
 
 It assumes you have a `requirements.txt` file with your PyPI dependencies.
@@ -23,11 +23,11 @@ bazel_dep(name = "rules_python", version = "0.0.0")
 
 pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
 pip.parse(
-    hub_name = "my_deps",
+    hub_name = "pypi",
     python_version = "3.11",
     requirements_lock = "//:requirements.txt",
 )
-use_repo(pip, "my_deps")
+use_repo(pip, "pypi")
 ```
 
 ## Using a WORKSPACE file
@@ -38,19 +38,14 @@ using Bzlmod. Here is a simplified setup to download the prebuilt runtimes.
 ```starlark
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
-
-# Update the SHA and VERSION to the lastest version available here:
-# https://github.com/bazelbuild/rules_python/releases.
-
-SHA="84aec9e21cc56fbc7f1335035a71c850d1b9b5cc6ff497306f84cced9a769841"
-
-VERSION="0.23.1"
+# Update the snippet based on the latest release below
+# https://github.com/bazelbuild/rules_python/releases
 
 http_archive(
     name = "rules_python",
-    sha256 = SHA,
-    strip_prefix = "rules_python-{}".format(VERSION),
-    url = "https://github.com/bazelbuild/rules_python/releases/download/{}/rules_python-{}.tar.gz".format(VERSION,VERSION),
+    sha256 = "ca77768989a7f311186a29747e3e95c936a41dffac779aff6b443db22290d913",
+    strip_prefix = "rules_python-0.36.0",
+    url = "https://github.com/bazelbuild/rules_python/releases/download/0.36.0/rules_python-0.36.0.tar.gz",
 )
 
 load("@rules_python//python:repositories.bzl", "py_repositories")
@@ -66,14 +61,12 @@ python_register_toolchains(
     python_version = "3.11",
 )
 
-load("@python_3_11//:defs.bzl", "interpreter")
-
 load("@rules_python//python:pip.bzl", "pip_parse")
 
 pip_parse(
-    ...
-    python_interpreter_target = interpreter,
-    ...
+    name = "pypi",
+    python_interpreter_target = "@python_3_11_host//:python",
+    requirements_lock = "//:requirements.txt",
 )
 ```
 
@@ -89,8 +82,8 @@ py_binary(
   name = "main",
   srcs = ["main.py"],
   deps = [
-      "@my_deps//foo",
-      "@my_deps//bar",
+      "@pypi//foo",
+      "@pypi//bar",
   ]
 )
 ```

docs/index.md

@@ -1,61 +1,71 @@
 # Python Rules for Bazel
 
-`rules_python` is the home for 4 major components:
-* the core Python rules -- `py_library`, `py_binary`, `py_test`,
-  `py_proto_library`, and related symbols that provide the basis for Python
-  support in Bazel.
+`rules_python` is the home for 4 major components with varying maturity levels.
 
-  This is subject to our breaking change policy outlined in the <support>.
-* Package installation rules for integrating with PyPI and other SimpleAPI
-  complying indexes.
+:::{topic} Core rules
 
-  This is still `experimental` and the APIs might change more often than the
-  core rules or you may experience regressions between the minor releases. In
-  that case, please raise tickets to the GH issues bug tracker.
-* `sphinxdocs` rules allowing users to generate documentation from bazel or
-  Python source code.
+The core Python rules -- `py_library`, `py_binary`, `py_test`,
+`py_proto_library`, and related symbols that provide the basis for Python
+support in Bazel.
 
-  This is available as is and without any guarantees. The semantic versioning
-  used by `rules_python` does not apply to bazel rules or the output.
-* `gazelle` plugin for generating `BUILD.bazel` files based on Python source
-  code.
+When using bazel 6, the core rules built into the Bazel binary, and the symbols
+in this repository are simple aliases. On bazel 7 and above `rules_python` uses
+a separate Starlark implementation,
+see {ref}`Migrating from the Bundled Rules` below.
 
-  This is available as is and without any guarantees. The semantic versioning
-  used by `rules_python` does not apply to the plugin.
+Once rules_python 1.0 is released, they will follow
+[semantic versioning](https://semver.org) and the breaking change policy
+outlined in the [support](support) page.
 
-Documentation for rules_python lives here and in the
-[Bazel Build Encyclopedia](https://docs.bazel.build/versions/master/be/python.html).
+:::
 
-Examples are in the {gh-path}`examples` directory.
+:::{topic} PyPI integration
 
-When using bazel 6, the core rules built into the Bazel binary, and the symbols
-in this repository are simple aliases. However, on bazel 7 and above starlark
-implementation in this repository is used.
-See {ref}`Migrating from the Bundled Rules` below.
+Package installation rules for integrating with PyPI and other SimpleAPI
+complying indexes.
+
+These rules are still `experimental` and the APIs might change more often
+than the core rules or you may experience regressions between the minor
+releases. In that case, please raise tickets to the GH issues bug tracker.
+
+:::
+
+:::{topic} Sphinxdocs
+
+`sphinxdocs` rules allowing users to generate documentation from bazel or
+Python source code.
+
+This is available as is and the semantic versioning used by `rules_python` does
+not apply to bazel rules or the output.
+
+:::
+
+:::{topic} Gazelle plugin
 
-The core rules are stable. Their implementation in Bazel is subject to Bazel's
-[backward compatibility policy](https://docs.bazel.build/versions/master/backward-compatibility.html).
-Once migrated to rules_python, they may evolve at a different
-rate, but this repository will still follow [semantic versioning](https://semver.org).
+`gazelle` plugin for generating `BUILD.bazel` files based on Python source
+code.
+
+This is available as is and the semantic versioning used by `rules_python` does
+not apply to the plugin.
+
+:::
 
 The Bazel community maintains this repository. Neither Google nor the Bazel
 team provides support for the code. However, this repository is part of the
 test suite used to vet new Bazel releases. See {gh-path}`How to contribute
 <CONTRIBUTING.md>` for information on our development workflow.
 
-## Bzlmod support
-
-- Status: GA
+## Examples
 
-See {gh-path}`Bzlmod support <BZLMOD_SUPPORT.md>` for any behaviour differences between
-`bzlmod` and `WORKSPACE`.
+This documentation is an example of `sphinxdocs` rules and the rest of the
+components have examples in the {gh-path}`examples` directory.
 
 ## Migrating from the bundled rules
 
 The core rules are currently available in Bazel as built-in symbols, but this
 form is deprecated. Instead, you should depend on rules_python in your
-`WORKSPACE` file and load the Python rules from
-`@rules_python//python:defs.bzl`.
+`WORKSPACE` or `MODULE.bazel` file and load the Python rules from
+`@rules_python//python:defs.bzl` or load paths described in the API documentation.
 
 A [buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md)
 fix is available to automatically migrate `BUILD` and `.bzl` files to add the
@@ -66,13 +76,18 @@ appropriate `load()` statements and rewrite uses of `native.py_*`.
 buildifier --lint=fix --warnings=native-py <files>
 ```
 
-Currently, the `WORKSPACE` file needs to be updated manually as per [Getting
-started](getting-started).
+Currently, the `WORKSPACE` file needs to be updated manually as per 
+[Getting started](getting-started).
 
 Note that Starlark-defined bundled symbols underneath
 `@bazel_tools//tools/python` are also deprecated. These are not yet rewritten
 by buildifier.
 
+## Migrating to bzlmod
+
+See {gh-path}`Bzlmod support <BZLMOD_SUPPORT.md>` for any behaviour differences between
+`bzlmod` and `WORKSPACE`.
+
 
 ```{toctree}
 :hidden: