8000 docs: fix crossrefs and allow function parameters to be referenced (#… · kshramt/rules_python@900d801 · GitHub
[go: up one dir, main page]
Skip to content

Commit 900d801

Browse files
rickeylevrickeylev
authored
docs: fix crossrefs and allow function parameters to be referenced (bazel-contrib#1585)
This fixes several old cross references from when the docs were plain stardoc generated markdown files. Also fixes how function parameters create their reference name so they can be referenced. Also formats conf.py to reduce future diffs. The only semantic change to conf.py is removing the suppressing of warnings.
1 parent 1b2019c commit 900d801

File tree

10 files changed

+55
-48
lines changed

10 files changed

+55
-48
lines changed

‎docs/sphinx/_includes/py_console_script_binary.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,5 +60,5 @@ py_console_script_binary(
6060
```
6161

6262
[specification]: https://packaging.python.org/en/latest/specifications/entry-points/
63-
[`py_console_script_binary.binary_rule`]: #py_console_script_binary-binary_rule
63+
[`py_console_script_binary.binary_rule`]: #py_console_script_binary_binary_rule
6464

‎docs/sphinx/conf.py

Lines changed: 37 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -32,25 +32,29 @@
3232
# Adapted from the template code:
3333
# https://github.com/readthedocs/readthedocs.org/blob/main/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl
3434
if os.environ.get("READTHEDOCS") == "True":
35-
# Must come first because it can interfere with other extensions, according
36-
# to the original conf.py template comments
37-
extensions.insert(0, "readthedocs_ext.readthedocs")
38-
39-
if os.environ.get("READTHEDOCS_VERSION_TYPE") == "external":
40-
# Insert after the main extension
41-
extensions.insert(1, "readthedocs_ext.external_version_warning")
42-
readthedocs_vcs_url = "http://github.com/bazelbuild/rules_python/pull/{}".format(
43-
os.environ.get("READTHEDOCS_VERSION", "")
44-
)
45-
# The build id isn't directly available, but it appears to be encoded
46-
# into the host name, so we can parse it from that. The format appears
47-
# to be `build-X-project-Y-Z`, where:
48-
# * X is an integer build id
49-
# * Y is an integer project id
50-
# * Z is the project name
51-
_build_id = os.environ.get("HOSTNAME", "build-0-project-0-rules-python")
52-
_build_id = _build_id.split("-")[1]
53-
readthedocs_build_url = f"https://readthedocs.org/projects/rules-python/builds/{_build_id}"
35+
# Must come first because it can interfere with other extensions, according
36+
# to the original conf.py template comments
37+
extensions.insert(0, "readthedocs_ext.readthedocs")
38+
39+
if os.environ.get("READTHEDOCS_VERSION_TYPE") == "external":
40+
# Insert after the main extension
41+
extensions.insert(1, "readthedocs_ext.external_version_warning")
42+
readthedocs_vcs_url = (
43+
"http://github.com/bazelbuild/rules_python/pull/{}".format(
44+
os.environ.get("READTHEDOCS_VERSION", "")
45+
)
46+
)
47+
# The build id isn't directly available, but it appears to be encoded
48+
# into the host name, so we can parse it from that. The format appears
49+
# to be `build-X-project-Y-Z`, where:
50+
# * X is an integer build id
51+
# * Y is an integer project id
52+
# * Z is the project name
53+
_build_id = os.environ.get("HOSTNAME", "build-0-project-0-rules-python")
54+
_build_id = _build_id.split("-")[1]
55+
readthedocs_build_url = (
56+
f"https://readthedocs.org/projects/rules-python/builds/{_build_id}"
57+
)
5458

5559
exclude_patterns = ["_includes/*"]
5660
templates_path = ["_templates"]
@@ -103,22 +107,21 @@
103107
# * For RTD builds, the flyout menu is always automatically injected,
104108
# so having it be True makes the flyout show up twice.
105109
"READTHEDOCS": False,
106-
'PRODUCTION_DOMAIN': "readthedocs.org",
110+
"PRODUCTION_DOMAIN": "readthedocs.org",
107111
# This is the path to a page's source (after the github user/repo/commit)
108112
"conf_py_path": "/docs/sphinx/",
109-
'github_user': 'bazelbuild',
110-
'github_repo': 'rules_python',
113+
"github_user": "bazelbuild",
114+
"github_repo": "rules_python",
111115
# The git version that was checked out, e.g. the tag or branch name
112-
'github_version': os.environ.get("READTHEDOCS_GIT_IDENTIFIER", ""),
116+
"github_version": os.environ.get("READTHEDOCS_GIT_IDENTIFIER", ""),
113117
# For local builds, the github link won't work. Disabling it replaces
114118
# it with a "view source" link to view the source Sphinx saw, which
115119
# is useful for local development.
116-
'display_github': os.environ.get("READTHEDOCS") == "True",
117-
'commit': os.environ.get("READTHEDOCS_GIT_COMMIT_HASH", "unknown commit"),
118-
120+
"display_github": os.environ.get("READTHEDOCS") == "True",
121+
"commit": os.environ.get("READTHEDOCS_GIT_COMMIT_HASH", "unknown commit"),
119122
# Used by readthedocs_ext.external_version_warning extension
120123
# This is the PR number being built
121-
'current_version': os.environ.get("READTHEDOCS_VERSION", ""),
124+
"current_version": os.environ.get("READTHEDOCS_VERSION", ""),
122125
}
123126

124127
# Keep this in sync with the stardoc templates
@@ -136,10 +139,12 @@
136139
# -- Options for EPUB output
137140
epub_show_urls = "footnote"
138141

139-
suppress_warnings = ["myst.header", "myst.xref_missing"]
142+
suppress_warnings = []
143+
140144

141145
def setup(app):
142-
# Pygments says it supports starlark, but it doesn't seem to actually
143-
# recognize `starlark` as a name. So just manually map it to python.
144-
from sphinx.highlighting import lexer_classes
145-
app.add_lexer('starlark', lexer_classes['python'])
146+
# Pygments says it supports starlark, but it doesn't seem to actually
147+
# recognize `starlark` as a name. So just manually map it to python.
148+
from sphinx.highlighting import lexer_classes
149+
150+
app.add_lexer("starlark", lexer_classes["python"])

‎docs/sphinx/pip.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
(pip-integration)=
22
# Pip Integration
33

4-
To pull in dependencies from PyPI, the `pip_parse` macro is used.
4+
To pull in dependencies from PyPI, the `pip_parse` function is used, which
5+
invokes `pip` to download and install dependencies from PyPI.
56

6-
7-
This macro wraps the [`pip_repository`](./pip_repository.md) rule that invokes `pip`.
87
In your WORKSPACE file:
98

109
```starlark

‎docs/sphinx/pypi-dependencies.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,9 @@
33
Using PyPI packages (aka "pip install") involves two main steps.
44

55
1. [Installing third party packages](#installing-third-party-packages)
6-
2. [Using third party packages as dependencies](#using-third-party-packages-as-dependencies)
6+
2. [Using third party packages as dependencies](#using-third-party-packages)
77

8+
{#installing-third-party-packages}
89
## Installing third party packages
910

1011
### Using bzlmod
@@ -77,6 +78,7 @@ transition. Still, some users of `pip_install` will need to replace their
7778
existing `requirements.txt` with a fully resolved set of dependencies using a
7879
tool such as `pip-tools` or the `compile_pip_requirements` repository rule.
7980

81+
{#using-third-party-packages}
8082
## Using third party packages as dependencies
8183

8284
Each extracted wheel repo contains a `py_library` target representing

‎python/packaging.bzl

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ This also has the advantage that stamping information is included in the wheel's
6666
implementation = _py_wheel_dist_impl,
6767
attrs = {
6868
"out": attr.string(doc = "name of the resulting directory", mandatory = True),
69-
"wheel": attr.label(doc = "a [py_wheel rule](/docs/packaging.md#py_wheel_rule)", providers = [PyWheelInfo]),
69+
"wheel": attr.label(doc = "a [py_wheel target](#py_wheel)", providers = [PyWheelInfo]),
7070
},
7171
)
7272

@@ -115,9 +115,9 @@ def py_wheel(name, twine = None, publish_args = [], **kwargs):
115115
)
116116
```
117117
118-
To publish the wheel to Pypi, the twine package is required.
119-
rules_python doesn't provide twine itself, see https://github.com/bazelbuild/rules_python/issues/1016
120-
However you can install it with pip_parse, just like we do in the WORKSPACE file in rules_python.
118+
To publish the wheel to PyPI, the twine package is required.
119+
rules_python doesn't provide twine itself, see [https://github.com/bazelbuild/rules_python/issues/1016].
120+
However you can install it with [pip_parse](#pip_parse), just like we do in the WORKSPACE file in rules_python.
121121
122122
Once you've installed twine, you can pass its label to the `twine` attribute of this macro,
123123
to get a "[name].publish" target.

‎python/pip.bzl

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ def pip_install(requirements = None, name = "pip", allow_pip_install = False, **
3737
requirements (Label): A 'requirements.txt' pip requirements file.
3838
name (str, optional): A unique name for the created external repository (default 'pip').
3939
allow_pip_install (bool, optional): change this to keep this rule working (default False).
40-
**kwargs (dict): Additional arguments to the [`pip_repository`](./pip_repository.md) repository rule.
40+
**kwargs (dict): Additional arguments to the [`pip_parse`](#pip_parse) repository rule.
4141
"""
4242

4343
if allow_pip_install:

‎python/pip_install/pip_repository.bzl

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -586,7 +586,6 @@ pip_repository = repository_rule(
586586
Those dependencies become available in a generated `requirements.bzl` file.
587587
You can instead check this `requirements.bzl` file into your repo, see the "vendoring" section below.
588588
589-
This macro wraps the [`pip_repository`](./pip_repository.md) rule that invokes `pip`.
590589
In your WORKSPACE file:
591590
592591
```starlark

‎python/private/py_wheel.bzl

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -106,10 +106,10 @@ For example:
106106
Note that Bazel's output filename cannot include the stamp information, as outputs must be known
107107
during the analysis phase and the stamp data is available only during the action execution.
108108
109-
The [`py_wheel`](/docs/packaging.md#py_wheel) macro produces a `.dist`-suffix target which creates a
109+
The [`py_wheel`](#py_wheel) macro produces a `.dist`-suffix target which creates a
110110
`dist/` folder containing the wheel with the stamped name, suitable for publishing.
111111
112-
See [`py_wheel_dist`](/docs/packaging.md#py_wheel_dist) for more info.
112+
See [`py_wheel_dist`](#py_wheel_dist) for more info.
113113
""",
114114
),
115115
"_stamp_flag": attr.label(
@@ -509,7 +509,7 @@ tries to locate `.runfiles` directory which is not packaged in the wheel.
509509
py_wheel = rule(
510510
implementation = py_wheel_lib.implementation,
511511
doc = """\
512-
Internal rule used by the [py_wheel macro](/docs/packaging.md#py_wheel).
512+
Internal rule used by the [py_wheel macro](#py_wheel).
513513
514514
These intentionally have the same name to avoid sharp edges with Bazel macros.
515515
For example, a `bazel query` for a user's `py_wheel` macro expands to `py_wheel` targets,

‎sphinxdocs/private/func_template.vm

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,9 @@ ${funcInfo.docString}
3232
{.params-box}
3333
#end
3434
## The .span wrapper is necessary so the trailing colon doesn't wrap
35-
:[${param.name}[¶](#$link){.headerlink}]{.span}: []{#$link}
36-
#if(!$param.getDefaultValue().isEmpty())(_default `${param.getDefaultValue()}`_) #end
35+
:[${param.name}[¶](#$link){.headerlink}]{.span}:
36+
{#$link}
37+
#if(!$param.getDefaultValue().isEmpty()) (_default `${param.getDefaultValue()}`_) #end
3738
#if(!$param.docString.isEmpty())
3839
$param.docString.replaceAll("$nl", "$nl ")
3940
#else

‎sphinxdocs/private/provider_template.vm

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ ${providerInfo.providerName}(## Comment to consume newline
1919
$providerInfo.docString
2020

2121
#if ($hasFields)
22+
{#${pnl}_fields}
2223
**FIELDS** [¶](#${pnl}_fields){.headerlink}
2324

2425
#foreach ($field in $providerInfo.getFieldInfoList())

0 commit comments

Comments
 (0)
0