Change how we embed docsite links in help text. #12261
Merged
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
[ci skip-build-wheels]
|
Note: tested locally and generated the v2.6 docs with this. See nice link at the top of https://www.pantsbuild.org/v2.6/docs/reference-python-protobuf for example. |
|
E.g.,
vs
|
|
The interesting changes are in build-support/bin/generate_docs.py and src/python/pants/util/docutil.py (and their tests). The rest is mostly the corresponding boilerplate changes. |
|
h/t to @alexey-tereshenkov-oxb for noticing the problem. This should comprehensively fix it across the site. |
Eric-Arellano
approved these changes
Jul 2, 2021
benjyw
added a commit
to benjyw/pants
that referenced
this pull request
Jul 2, 2021
The issue is that we needed to generate URLs that work when displayed in help messages on the console, but that also cross-link correctly when those same help messages are used to generate docsite reference pages. Previously we used raw links with the doc version embedded in the URL (e.g., https://www.pantsbuild.org/v2.6/docs/protobuf). And in many cases we had to enclose that URL in parentheses to avoid issues with readme.com's linkifier (such as it including a trailing period in the URL). However it turns out that readme.com now modifies such URLs in markdown to add the version. So https://www.pantsbuild.org/v2.6/docs/protobuf turns into https://www.pantsbuild.org/v2.6/v2.6/docs/protobuf which is a bad link. This change makes all this much more robust by moving the logic from help string authoring time to docsite page generation time. When authoring help strings you simply write URLs (either raw or, preferably, using the doc_url() util function). The code that renders docsite pages detects docsite URLs in strings and rewrites them to proper intra-doc markdown ([title](doc:slug)). It does so by fetching the titles from the live pages. This does assume that any links in generated docs are to files that already exist on the docsite. But this is true today and is likely to continue to be true (since we have to know the page slug anyway). [ci skip-build-wheels]
|
Cherry-picked to 2.6. It doesn't apply cleanly on 2.5, so I'd say no to that. |
benjyw
added a commit
that referenced
this pull request
Jul 2, 2021
Cherry-pick of #12261 [ci skip-build-wheels]
illicitonion
added a commit
to illicitonion/pants
that referenced
this pull request
Jul 9, 2021
Internal changes omitted from the release notes: * [internal] `./pants lock` uses transitive closure as inputs ([pantsbuild#12312](pantsbuild#12312)) * [internal] Add experimental `./pants lock` to generate a lockfile with pip-compile ([pantsbuild#12300](pantsbuild#12300)) * upgrade tokio and futures crates ([pantsbuild#12308](pantsbuild#12308)) * upgrade tonic, tower, and hyper crates ([pantsbuild#12294](pantsbuild#12294)) * Set up pants to use the latest version of humbug ([pantsbuild#12302](pantsbuild#12302)) * Refactor BUILD file parsing. ([pantsbuild#12279](pantsbuild#12279)) * Use get_type_hints() to get typed type hints. ([pantsbuild#12287](pantsbuild#12287)) * [internal] Fix parameters of convert_source_to_sources_test ([pantsbuild#12274](pantsbuild#12274)) * Fix assert arguments in a test ([pantsbuild#12273](pantsbuild#12273)) * Introduce a native pants client. ([pantsbuild#11922](pantsbuild#11922)) * Don't run CI in forks ([pantsbuild#12267](pantsbuild#12267)) * Change how we embed docsite links in help text. ([pantsbuild#12261](pantsbuild#12261))
Merged
illicitonion
added a commit
to illicitonion/pants
that referenced
this pull request
Jul 9, 2021
Internal changes omitted from the release notes: * [internal] `./pants lock` uses transitive closure as inputs ([pantsbuild#12312](pantsbuild#12312)) * [internal] Add experimental `./pants lock` to generate a lockfile with pip-compile ([pantsbuild#12300](pantsbuild#12300)) * upgrade tokio and futures crates ([pantsbuild#12308](pantsbuild#12308)) * upgrade tonic, tower, and hyper crates ([pantsbuild#12294](pantsbuild#12294)) * Set up pants to use the latest version of humbug ([pantsbuild#12302](pantsbuild#12302)) * Refactor BUILD file parsing. ([pantsbuild#12279](pantsbuild#12279)) * Use get_type_hints() to get typed type hints. ([pantsbuild#12287](pantsbuild#12287)) * [internal] Fix parameters of convert_source_to_sources_test ([pantsbuild#12274](pantsbuild#12274)) * Fix assert arguments in a test ([pantsbuild#12273](pantsbuild#12273)) * Introduce a native pants client. ([pantsbuild#11922](pantsbuild#11922)) * Don't run CI in forks ([pantsbuild#12267](pantsbuild#12267)) * Change how we embed docsite links in help text. ([pantsbuild#12261](pantsbuild#12261))
illicitonion
added a commit
to illicitonion/pants
that referenced
this pull request
Jul 9, 2021
Internal changes omitted from the release notes: * [internal] `./pants lock` uses transitive closure as inputs ([pantsbuild#12312](pantsbuild#12312)) * [internal] Add experimental `./pants lock` to generate a lockfile with pip-compile ([pantsbuild#12300](pantsbuild#12300)) * upgrade tokio and futures crates ([pantsbuild#12308](pantsbuild#12308)) * upgrade tonic, tower, and hyper crates ([pantsbuild#12294](pantsbuild#12294)) * Set up pants to use the latest version of humbug ([pantsbuild#12302](pantsbuild#12302)) * Refactor BUILD file parsing. ([pantsbuild#12279](pantsbuild#12279)) * Use get_type_hints() to get typed type hints. ([pantsbuild#12287](pantsbuild#12287)) * [internal] Fix parameters of convert_source_to_sources_test ([pantsbuild#12274](pantsbuild#12274)) * Fix assert arguments in a test ([pantsbuild#12273](pantsbuild#12273)) * Introduce a native pants client. ([pantsbuild#11922](pantsbuild#11922)) * Don't run CI in forks ([pantsbuild#12267](pantsbuild#12267)) * Change how we embed docsite links in help text. ([pantsbuild#12261](pantsbuild#12261)) * Add JavacSubsystem and JavacBinary, allowing user-configurable JVM selection ([pantsbuild#12283](pantsbuild#12283)) * Revert "Deprecate unused `--process-execution-local-enable-nailgun` (pantsbuild#11600)" ([pantsbuild#12257](pantsbuild#12257))
illicitonion
added a commit
that referenced
this pull request
Jul 9, 2021
Internal changes omitted from the release notes: * [internal] `./pants lock` uses transitive closure as inputs ([#12312](#12312)) * [internal] Add experimental `./pants lock` to generate a lockfile with pip-compile ([#12300](#12300)) * upgrade tokio and futures crates ([#12308](#12308)) * upgrade tonic, tower, and hyper crates ([#12294](#12294)) * Set up pants to use the latest version of humbug ([#12302](#12302)) * Refactor BUILD file parsing. ([#12279](#12279)) * Use get_type_hints() to get typed type hints. ([#12287](#12287)) * [internal] Fix parameters of convert_source_to_sources_test ([#12274](#12274)) * Fix assert arguments in a test ([#12273](#12273)) * Introduce a native pants client. ([#11922](#11922)) * Don't run CI in forks ([#12267](#12267)) * Change how we embed docsite links in help text. ([#12261](#12261)) * Add JavacSubsystem and JavacBinary, allowing user-configurable JVM selection ([#12283](#12283)) * Revert "Deprecate unused `--process-execution-local-enable-nailgun` (#11600)" ([#12257](#12257))
Eric-Arellano
added a commit
that referenced
this pull request
Jul 14, 2021
Eric-Arellano
added a commit
to Eric-Arellano/pants
that referenced
this pull request
Jul 15, 2021
The code from pantsbuild#12261 is only used in `generate_docs.py`, but was defind in `docutil.py` so it gets bundled into pantsbuild.pants. By moving out of `docutil.py`, we remove Pants's dependency on `requests`. [ci skip-rust] [ci skip-build-wheels]
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 issue is that we needed to generate URLs that work when displayed in
help messages on the console, but that also cross-link correctly when those same
help messages are used to generate docsite reference pages.
Previously we used raw links with the doc version embedded in the URL (e.g.,
https://www.pantsbuild.org/v2.6/docs/protobuf). And in many cases we had
to enclose that URL in parentheses to avoid issues with readme.com's linkifier
(such as it including a trailing period in the URL).
However it turns out that readme.com now modifies such URLs in markdown
to add the version. So https://www.pantsbuild.org/v2.6/docs/protobuf turns into
https://www.pantsbuild.org/v2.6/v2.6/docs/protobuf which is a bad link.
This change makes all this much more robust by moving the logic from help string
authoring time to docsite page generation time. When authoring help strings you simply
write URLs (either raw or, preferably, using the doc_url() util function). The code that
renders docsite pages detects docsite URLs in strings and rewrites them to proper
intra-doc markdown (
[title](doc:slug)). It does so by fetching the titles from the livepages.
This does assume that any links in generated docs are to files that already exist on the docsite.
But this is true today and is likely to continue to be true (since we have to know the page slug anyway).
[ci skip-build-wheels]