| commit | 509b02f8c719decb40f4731b735e65b6545ceea0 | [log] [tgz] |
|---|---|---|
| author | Richard Levasseur <rlevasseur@google.com> | Tue Dec 19 16:51:44 2023 -0800 |
| committer | GitHub <noreply@github.com> | Wed Dec 20 00:51:44 2023 +0000 |
| tree | d9f29f6f039c859f7cface9ab7d027e306d867d2 | |
| parent | 87a3a54cd937b037f531fedac243350933dd1eb7 [diff] |
docs: use stardoc proto output to generate markdown docs (#1629)
The template language Stardoc uses (Velocity) is niche and fairly
esoteric, and requires a lot of experimenting to understand how to
make it produce the desired output. In particular, it largely assumes
whitespace doesn't matter, which makes it a poor fit for generating
Markdown, where whitespace often does matter.
Instead, a small Python program is used to consume the binary proto
output of Stardoc, which converts it to Markdown. This also makes it
easier to customize the overall output and re-use code for the different
types of objects rendered.
The visible changes to the docs are:
* Module extensions are now documented
* Repository rules follow the style of the other generated docs
* Fixed the rendering of pip_repository docs -- it had an h2
section which broke the section grouping of the API objects.
* Puts some padding between the border and content for text in
params/attrs/fields listings.
Other notable changes:
* Make RTD builds use bzlmod. This is necessary so that the pip
extension can be documented. It loads
`@pythons_hub//:interpreters.bzl`, but that repo is only created
when bzlmod is enabled)
---------
Co-authored-by: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
This repository is the home of 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. It also contains package installation rules for integrating with PyPI and other indices.
Documentation for rules_python is at https://rules-python.readthedocs.io and in the Bazel Build Encyclopedia.
Examples live in the examples directory.
Currently, the core rules build into the Bazel binary, and the symbols in this repository are simple aliases. However, we are migrating the rules to Starlark and removing them from the Bazel binary. Therefore, the future-proof way to depend on Python rules is via this repository. SeeMigrating from the Bundled Rules below.
The core rules are stable. Their implementation in Bazel is subject to Bazel's backward compatibility policy. Once migrated to rules_python, they may evolve at a different rate, but this repository will still follow semantic versioning.
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 How to contribute page for information on our development workflow.
For detailed documentation, see https://rules-python.readthedocs.io
See Bzlmod support for more details.