docs: use stardoc proto output to generate markdown docs #1629
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Ah doh, need to fix a few test failures before review. |
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)
rickeylev
force-pushed
the
docs.proto.template
branch
from
3174d4c
to
9634f3d
Compare
for some reason, it crashes the stardoc interpreter under bazel 6.
…on into docs.proto.template
|
Ok, tests fixed. Just windows flakes left. |
aignas
reviewed
Dec 19, 2023
…on into docs.proto.template
Co-authored-by: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
Co-authored-by: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
aignas
approved these changes
Dec 20, 2023
| @@ -12,8 +12,10 @@ | |||
| # See the License for the specific language governing permissions and | |||
| # limitations under the License. | |||
|
|
|||
| load("@docs_deps//:requirements.bzl", "requirement") | |||
| load("@rules_python//python:pip.bzl", "compile_pip_requirements") | |||
| load("@dev_pip//:requirements.bzl", "requirement") | |||
There was a problem hiding this comment.
nit: technically I think we don't need this macro anymore as the same alias labels can be accessed from WORKSPACE and MODULE.bazel setups.
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
section which broke the section grouping of the API objects.
params/attrs/fields listings.
Other notable changes:
extension can be documented. It loads
@pythons_hub//:interpreters.bzl, but that repo is only createdwhen bzlmod is enabled)