Add user guide doc with not well known features - #691
Merged
xdelaruelle merged 5 commits intoAug 31, 2026
Conversation
Signed-off-by: Adrien Cotte <adrien.cotte@asplus.fr>
Use literal markup on command, option and file names in section titles and move the mogui section next to the other collection-related features. Fix typos and grammar: "Lesser know" document title, garbled "Advanced specifications specifiers" section title, doubled slash in spider example paths, nested inline markup in the presentation title, missing articles and various wording issues. Also fix the module use cross-reference so it resolves, correct the Spack package name to py-modules-gui, and harmonize inline markup, line wrapping and example output spacing. Assisted-by: Claude:claude-fable-5 Signed-off-by: Xavier Delaruelle <xavier.delaruelle@cea.fr>
Assisted-by: Claude:claude-fable-5 Signed-off-by: Xavier Delaruelle <xavier.delaruelle@cea.fr>
Demonstrate what the described features bring by showing the output of the example commands, compared when relevant against a plain module avail run listing all existing modulefiles: - --output: empty LIST reporting only module names, plus the "+" and "-" LIST prefixes that adjust the currently configured element list - --latest and --default: filtered version lists, explaining that the default version is either explicitly set or implicitly the highest - --timer and --debug: timing report, debug messages and per-procedure execution time reports when both options are combined - module-tag: applied tag reported along the module name and a purge attempt on a sticky module showing its unload is skipped Rework the prereq section: present this command as a way to declare requirements, that are automatically loaded when the auto_handling mode is enabled, rather than a check that dependencies are loaded. Warn that requirements must not be declared within a condition block, as no requirement rule gets defined when the required module is already loaded. Mention that the module load modulefile command equally defines a requirement rule, loading missing modules even when auto_handling is disabled, and acting as a logical AND over the specified modules whereas prereq acts as a logical OR. Rework the conflict section: conflicting modules are automatically unloaded when the conflict_unload and auto_handling modes are enabled, so demonstrate this mechanism rather than advertising the --force option to bypass the conflict error. Describe the reflexive conflict pattern that ensures only one version of a module can be loaded at a time. Precise in the tip about unique_name_loaded that this option applies to all existing modules, which may not fit when application configurations are also handled through modulefiles. Assisted-by: Claude:claude-fable-5 Signed-off-by: Xavier Delaruelle <xavier.delaruelle@cea.fr>
Turn console code-blocks into parsed-literal blocks using the color roles rendering output like in a terminal, as done in MIGRATING.rst. Modulepaths, default versions, tags, variants, messages and debugging output get the colors and styles of the real command output, whose rendering slightly differs from the monochrome mode: the default version is underlined rather than reported with a "(default)" marker and the sticky tag is rendered with a background color rather than an "<S>" abbreviation. Assisted-by: Claude:claude-fable-5 Signed-off-by: Xavier Delaruelle <xavier.delaruelle@cea.fr>
xdelaruelle
force-pushed
the
doc/lesser_known_features
branch
from
August 31, 2026 05:29
349e474 to
b33dc89
Compare
xdelaruelle
approved these changes
Aug 31, 2026
xdelaruelle
left a comment
xdelaruelle
left a comment
Collaborator
There was a problem hiding this comment.
Added several commits to improve docs. LGTM.
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
2 participants
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.
Add a new user guide section in the documentation.
--output=LISTspider--latestand--default--indepthand--no-indepth--jsonmoguistashcommandsmodule editmodule lintsource-shsh-to-modmod-to-shprereqconflict--timerand--debug.modulercfilesmodule-tagmodule-hidemodule-forbidmodule-virtualFixes #610