From f2aaeef60f8c4a263670a2b2d56279daab2c87a8 Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Sun, 25 Aug 2024 22:31:43 -0700 Subject: [PATCH] wip: fix some doc warnings --- CHANGELOG.md | 3 +-- docs/api/index.md | 1 - docs/conf.py | 2 +- python/private/pypi/pip_repository.bzl | 4 +++- sphinxdocs/docs/sphinx-bzl.md | 26 ++++++++++---------------- 5 files changed, 15 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dcd8576b98..6a901bb236 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -767,8 +767,7 @@ Breaking changes: ### Added -* (bzlmod, entry_point) Added - [`py_console_script_binary`](./docs/py_console_script_binary.md), which +* (bzlmod, entry_point) Added {obj}`py_console_script_binary`, which allows adding custom dependencies to a package's entry points and customizing the `py_binary` rule used to build it. diff --git a/docs/api/index.md b/docs/api/index.md index 87e17e1a8f..0a5f1ed1a5 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -2,6 +2,5 @@ ```{toctree} :glob: -* */index ``` diff --git a/docs/conf.py b/docs/conf.py index ba628b6fc1..d65d5b51f0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,7 +59,7 @@ autodoc2_docstring_parser_regexes = [ (".*", "myst"), ] - + # NOTE: The redirects generation will clobber existing files. redirects = { "api/tools/precompiler/index": "/api/rules_python/tools/precompiler/index.html", diff --git a/python/private/pypi/pip_repository.bzl b/python/private/pypi/pip_repository.bzl index 0c9e300a4d..90cda77465 100644 --- a/python/private/pypi/pip_repository.bzl +++ b/python/private/pypi/pip_repository.bzl @@ -326,7 +326,9 @@ alias( ) ``` -### Vendoring the requirements.bzl file +:::{rubric} Vendoring the requirements.bzl file +:heading-level: 3 +::: In some cases you may not want to generate the requirements.bzl file as a repository rule while Bazel is fetching dependencies. For example, if you produce a reusable Bazel module diff --git a/sphinxdocs/docs/sphinx-bzl.md b/sphinxdocs/docs/sphinx-bzl.md index 0edd3202b6..bb51b6cdc6 100644 --- a/sphinxdocs/docs/sphinx-bzl.md +++ b/sphinxdocs/docs/sphinx-bzl.md @@ -140,6 +140,16 @@ Refer to a target. :::{rst:role} bzl:type Refer to a type or type expression; can also be used in argument documentation. + +``` +def func(arg): + """Do stuff + + Args: + arg: {type}`int | str` the arg + """ + print(arg + 1) +``` ::: ## Special roles @@ -187,22 +197,6 @@ def func(): ``` ::: -:::{rst:role} bzl:type - -Indicates the type of an argument for a function. Use it in the Args doc of -a function. - -``` -def func(arg): - """Do stuff - - Args: - arg: {type}`int` - """ - print(arg + 1) -``` -::: - ## Directives Most directives are automatically generated by `sphinx_stardoc`. Here, we only