borg help environment: new help topic about env variables - #10063
Merged
Conversation
…backup#10061 Add an "environment" help topic (alias: "env") showing the documentation about the environment variables borg supports, like borg help already does for patterns, placeholders, compression and match-archives. The help topic is now the single source of that documentation: scripts/make.py build_usage generates docs/usage/general/environment.rst.inc from it (and skips it on the misc. help docs page, where it would duplicate the "General" chapter's section), and build_man already generates a borg-environment(1) man page from any help topic. The text was adapted a bit so that it renders well both via sphinx and via nanorst on the terminal: the list-table, note directive and hyperlink targets were replaced by constructs nanorst understands. nanorst: end a code block when a following line is less indented than the code block's contents (instead of the hardcoded "less than 4 spaces" rule), so code blocks nested inside definition lists do not swallow the text following them any more. Also, borg help <topic> now resolves :ref: references like the command epilogs already did. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #10063 +/- ##
==========================================
- Coverage 86.76% 86.66% -0.10%
==========================================
Files 98 98
Lines 17085 17098 +13
Branches 2586 2590 +4
==========================================
- Hits 14823 14818 -5
- Misses 1570 1585 +15
- Partials 692 695 +3 ☔ View full report in Codecov by Harness. |
This file contains hidden or 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
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.
Fixes #10061.
borg help environment(alias:borg help env) now shows the documentation about the environment variables borg supports, likeborg helpalready does for patterns, placeholders, match-archives and compression.build_manautomatically produces aborg-environment(1)man page from the new topic.To avoid duplicating the docs, the help topic is now the single source of that documentation:
scripts/make.py build_usagegeneratesdocs/usage/general/environment.rst.incfrom it (and skips this topic on the misc. help docs page, where it would just duplicate the "General" chapter's section). The text was adapted a bit so it renders well both via sphinx and via nanorst on the terminal: the list-table, the note directive and the hyperlink targets were replaced by constructs nanorst understands (plain code-block table, plain URLs); the:ref:roles were kept and get substituted with plain text on the terminal like the command epilogs already do.nanorst change: a code block now ends when a following line is less indented than the code block's contents, instead of the hardcoded "less than 4 spaces" rule. Without this, the many code blocks nested inside the environment topic's definition lists would swallow the text following them (the compression topic's obfuscate section had the same problem). Covered by new tests.
Checked:
borg help environment/borg help envrender cleanly on the terminal (no leftover rst markup).env_varslabel still resolves (the auto-generated marker comment must come after the heading, otherwise it breaks the label-to-title association - noted in make.py).🤖 Generated with Claude Code