docs: allow manual edits to generated docs (#1478)
Before this PR the documentation used to be next to the source. With
the adjustment of how we generate the markdown files, we can keep user
friendly documentation in markdown and leave the API docs in the `.bzl`
source code. This improve the maintainability of the docs as editors
have better support for editing markdown in markdown files as opposed to
docstrings within `.bzl` files.
NOTE: This is implemented via a genrule in order to not expose a macro
as an
consumable API.
Summary:
- chore: mark the documentation files as non-generated
- chore: chmod -x markdown files
- feat: adjust doc generation to retain headers and modify the header
- refactor: move the docs from .bzl and improve them
Work towards #1332
diff --git a/.gitattributes b/.gitattributes
index 64d09ff..e4e5d4b 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,2 +1 @@
-docs/*.md linguist-generated=true
tools/publish/*.txt linguist-generated=true
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
index 1b41a10..3d61144 100644
--- a/docs/BUILD.bazel
+++ b/docs/BUILD.bazel
@@ -23,15 +23,17 @@
licenses(["notice"]) # Apache 2.0
-_DOCS = {
- "packaging": "//docs:packaging-docs",
- "pip": "//docs:pip-docs",
- "pip_repository": "//docs:pip-repository",
- "py_cc_toolchain": "//docs:py_cc_toolchain-docs",
- "py_cc_toolchain_info": "//docs:py_cc_toolchain_info-docs",
- "py_console_script_binary": "//docs:py-console-script-binary",
- "python": "//docs:core-docs",
-}
+_DOCS = [
+ "packaging",
+ "pip",
+ "pip_repository",
+ "py_cc_toolchain",
+ "py_cc_toolchain_info",
+ # TODO @aignas 2023-10-09: move some of the example code from the `.bzl` files
+ # to the markdown once #1476 is merged.
+ "py_console_script_binary",
+ "python",
+]
# Temporary compatibility aliases for some other projects depending on the old
# bzl_library targets.
@@ -74,7 +76,7 @@
stardoc(
name = "core-docs",
- out = "python.md_",
+ out = "python.md.gen",
input = "//python:defs.bzl",
target_compatible_with = _TARGET_COMPATIBLE_WITH,
deps = [
@@ -84,7 +86,7 @@
stardoc(
name = "pip-docs",
- out = "pip.md_",
+ out = "pip.md.gen",
input = "//python:pip.bzl",
target_compatible_with = _TARGET_COMPATIBLE_WITH,
deps = [
@@ -94,7 +96,7 @@
stardoc(
name = "pip-repository",
- out = "pip_repository.md_",
+ out = "pip_repository.md.gen",
input = "//python/pip_install:pip_repository.bzl",
target_compatible_with = _TARGET_COMPATIBLE_WITH,
deps = [
@@ -104,7 +106,7 @@
stardoc(
name = "py-console-script-binary",
- out = "py_console_script_binary.md_",
+ out = "py_console_script_binary.md.gen",
input = "//python/entry_points:py_console_script_binary.bzl",
target_compatible_with = _TARGET_COMPATIBLE_WITH,
deps = [
@@ -114,7 +116,7 @@
stardoc(
name = "packaging-docs",
- out = "packaging.md_",
+ out = "packaging.md.gen",
input = "//python:packaging.bzl",
target_compatible_with = _TARGET_COMPATIBLE_WITH,
deps = ["//python:packaging_bzl"],
@@ -122,7 +124,7 @@
stardoc(
name = "py_cc_toolchain-docs",
- out = "py_cc_toolchain.md_",
+ out = "py_cc_toolchain.md.gen",
# NOTE: The public file isn't used as the input because it would document
# the macro, which doesn't have the attribute documentation. The macro
# doesn't do anything interesting to users, so bypass it to avoid having to
@@ -134,12 +136,36 @@
stardoc(
name = "py_cc_toolchain_info-docs",
- out = "py_cc_toolchain_info.md_",
+ out = "py_cc_toolchain_info.md.gen",
input = "//python/cc:py_cc_toolchain_info.bzl",
deps = ["//python/cc:py_cc_toolchain_info_bzl"],
)
[
+ # retain any modifications made by the maintainers above the generated part
+ genrule(
+ name = "merge_" + k,
+ srcs = [
+ k + ".md",
+ k + ".md.gen",
+ ],
+ outs = [k + ".md_"],
+ cmd = ";".join([
+ "sed -En '/{comment_bait}/q;p' <$(location {first}) > $@",
+ "sed -E 's/{comment_doc}/{comment_note}/g' $(location {second}) >> $@",
+ ]).format(
+ comment_bait = "Stardoc: http:..skydoc.bazel.build -->",
+ comment_doc = "^<!.*(Stardoc:.*skydoc.bazel.build.*)",
+ comment_note = "<!-- Everything including and below this line replaced " +
+ "with output from \\1",
+ first = k + ".md",
+ second = k + ".md.gen",
+ ),
+ )
+ for k in _DOCS
+]
+
+[
diff_test(
name = "check_" + k,
failure_message = "Please run: bazel run //docs:update",
@@ -148,7 +174,7 @@
tags = ["doc_check_test"],
target_compatible_with = _TARGET_COMPATIBLE_WITH,
)
- for k in _DOCS.keys()
+ for k in _DOCS
]
write_file(
@@ -159,7 +185,7 @@
"cd $BUILD_WORKSPACE_DIRECTORY",
] + [
"cp -fv bazel-bin/docs/{0}.md_ docs/{0}.md".format(k)
- for k in _DOCS.keys()
+ for k in _DOCS
],
target_compatible_with = _TARGET_COMPATIBLE_WITH,
)
@@ -167,6 +193,6 @@
sh_binary(
name = "update",
srcs = ["update.sh"],
- data = _DOCS.values(),
+ data = ["merge_" + k for k in _DOCS],
target_compatible_with = _TARGET_COMPATIBLE_WITH,
)
diff --git a/docs/packaging.md b/docs/packaging.md
old mode 100755
new mode 100644
index b6cbbba..ae7c473
--- a/docs/packaging.md
+++ b/docs/packaging.md
@@ -1,4 +1,6 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+# Packaging
+
+<!-- Everything including and below this line replaced with output from Stardoc: http://skydoc.bazel.build -->
Public API for for building wheels.
diff --git a/docs/pip.md b/docs/pip.md
index c533bec..f84262a 100644
--- a/docs/pip.md
+++ b/docs/pip.md
@@ -1,4 +1,11 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+# pip integration
+
+This contains a set of rules that are used to support inclusion of third-party
+dependencies via fully locked `requirements.txt` files. Some of the exported
+symbols should not be used and they are either undocumented here or marked as
+for internal use only.
+
+<!-- Everything including and below this line replaced with output from Stardoc: http://skydoc.bazel.build -->
Import pip requirements into Bazel.
diff --git a/docs/pip_repository.md b/docs/pip_repository.md
index 0ea6ad4..a3db0de 100644
--- a/docs/pip_repository.md
+++ b/docs/pip_repository.md
@@ -1,4 +1,9 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+# pip integration
+
+Out of items documented below only `package_annotation` annotation is available
+for general usage. Any other APIs are subject to change.
+
+<!-- Everything including and below this line replaced with output from Stardoc: http://skydoc.bazel.build -->
diff --git a/docs/py_cc_toolchain.md b/docs/py_cc_toolchain.md
index 9b9360c..49fe7ef 100644
--- a/docs/py_cc_toolchain.md
+++ b/docs/py_cc_toolchain.md
@@ -1,4 +1,6 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+# Python C/C++ toolchain rule
+
+<!-- Everything including and below this line replaced with output from Stardoc: http://skydoc.bazel.build -->
Implementation of py_cc_toolchain rule.
diff --git a/docs/py_cc_toolchain_info.md b/docs/py_cc_toolchain_info.md
index f0a94f4..42dad95 100644
--- a/docs/py_cc_toolchain_info.md
+++ b/docs/py_cc_toolchain_info.md
@@ -1,4 +1,6 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+# Python C/C++ toolchain provider info.
+
+<!-- Everything including and below this line replaced with output from Stardoc: http://skydoc.bazel.build -->
Provider for C/C++ information about the Python runtime.
diff --git a/docs/py_console_script_binary.md b/docs/py_console_script_binary.md
index 5f88683..e7cc9bd 100644
--- a/docs/py_console_script_binary.md
+++ b/docs/py_console_script_binary.md
@@ -1,6 +1,7 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+# //pytho/entrypoints:py_console_script_binary
-Creates an executable (a non-test binary) for console_script entry points.
+This rule is to make it easier to generate `console_script` entry points
+as per Python [specification].
Generate a `py_binary` target for a particular console_script `entry_point`
from a PyPI package, e.g. for creating an executable `pylint` target use:
@@ -14,9 +15,9 @@
```
Or for more advanced setups you can also specify extra dependencies and the
-exact script name you want to call. It is useful for tools like flake8, pylint,
-pytest, which have plugin discovery methods and discover dependencies from the
-PyPI packages available in the PYTHONPATH.
+exact script name you want to call. It is useful for tools like `flake8`, `pylint`,
+`pytest`, which have plugin discovery methods and discover dependencies from the
+PyPI packages available in the `PYTHONPATH`.
```starlark
load("@rules_python//python/entry_points:py_console_script_binary.bzl", "py_console_script_binary")
@@ -46,7 +47,7 @@
)
```
-Alternatively, the `py_console_script_binary.binary_rule` arg can be passed
+Alternatively, the [`py_console_script_binary.binary_rule`] arg can be passed
the version-bound `py_binary` symbol, or any other `py_binary`-compatible rule
of your choosing:
```starlark
@@ -60,6 +61,14 @@
)
```
+[specification]: https://packaging.python.org/en/latest/specifications/entry-points/
+[`py_console_script_binary.binary_rule`]: #py_console_script_binary-binary_rule
+
+
+<!-- Everything including and below this line replaced with output from Stardoc: http://skydoc.bazel.build -->
+
+Creates an executable (a non-test binary) for console_script entry points.
+
<a id="py_console_script_binary"></a>
## py_console_script_binary
diff --git a/docs/python.md b/docs/python.md
old mode 100755
new mode 100644
index 6924507..b0f14b3
--- a/docs/python.md
+++ b/docs/python.md
@@ -1,4 +1,6 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+# Core Python rules
+
+<!-- Everything including and below this line replaced with output from Stardoc: http://skydoc.bazel.build -->
Core rules for building Python projects.
diff --git a/python/entry_points/py_console_script_binary.bzl b/python/entry_points/py_console_script_binary.bzl
index 1991bba..60fbd8c 100644
--- a/python/entry_points/py_console_script_binary.bzl
+++ b/python/entry_points/py_console_script_binary.bzl
@@ -14,64 +14,6 @@
"""
Creates an executable (a non-test binary) for console_script entry points.
-
-Generate a `py_binary` target for a particular console_script `entry_point`
-from a PyPI package, e.g. for creating an executable `pylint` target use:
-```starlark
-load("@rules_python//python/entry_points:py_console_script_binary.bzl", "py_console_script_binary")
-
-py_console_script_binary(
- name = "pylint",
- pkg = "@pip//pylint",
-)
-```
-
-Or for more advanced setups you can also specify extra dependencies and the
-exact script name you want to call. It is useful for tools like flake8, pylint,
-pytest, which have plugin discovery methods and discover dependencies from the
-PyPI packages available in the PYTHONPATH.
-```starlark
-load("@rules_python//python/entry_points:py_console_script_binary.bzl", "py_console_script_binary")
-
-py_console_script_binary(
- name = "pylint_with_deps",
- pkg = "@pip//pylint",
- # Because `pylint` has multiple console_scripts available, we have to
- # specify which we want if the name of the target name 'pylint_with_deps'
- # cannot be used to guess the entry_point script.
- script = "pylint",
- deps = [
- # One can add extra dependencies to the entry point.
- # This specifically allows us to add plugins to pylint.
- "@pip//pylint_print",
- ],
-)
-```
-
-A specific Python version can be forced by using the generated version-aware
-wrappers, e.g. to force Python 3.9:
-```starlark
-load("@python_versions//3.9:defs.bzl", "py_console_script_binary")
-
-py_console_script_binary(
- name = "yamllint",
- pkg = "@pip//yamllint",
-)
-```
-
-Alternatively, the `py_console_script_binary.binary_rule` arg can be passed
-the version-bound `py_binary` symbol, or any other `py_binary`-compatible rule
-of your choosing:
-```starlark
-load("@python_versions//3.9:defs.bzl", "py_binary")
-load("@rules_python//python/entry_points:py_console_script_binary.bzl", "py_console_script_binary")
-
-py_console_script_binary(
- name = "yamllint",
- pkg = "@pip//yamllint:pkg",
- binary_rule = py_binary,
-)
-```
"""
load("//python/private:py_console_script_binary.bzl", _py_console_script_binary = "py_console_script_binary")
