diff --git a/framework/doc/globals.yml b/framework/doc/globals.yml index 03c33b56dc41..e309d22b1b36 100644 --- a/framework/doc/globals.yml +++ b/framework/doc/globals.yml @@ -32,3 +32,4 @@ LinearFVBCs: /LinearFVBCs/index.md GitHub: https://github.com Gmsh: https://gmsh.info/ SLEPc: https://slepc.upv.es/ +CIVET: https://github.com/idaholab/civet diff --git a/modules/doc/content/newsletter/2025/2025_01.md b/modules/doc/content/newsletter/2025/2025_01.md index 7878b96b0c38..fa62096b5ea6 100644 --- a/modules/doc/content/newsletter/2025/2025_01.md +++ b/modules/doc/content/newsletter/2025/2025_01.md @@ -15,4 +15,9 @@ for a complete description of all MOOSE changes. ## Bug Fixes and Minor Enhancements +- The MooseDocs [extensions/civet.md] `mergeresults` command now uses the current hash used to build + the documentation, rather than using the most up-to-date commit information from the remote code + repository. This allows documentation built from earlier versions of MOOSE-based code to have + consistent CI links for their version. + ## Conda Package Changes diff --git a/python/MooseDocs/extensions/civet.py b/python/MooseDocs/extensions/civet.py index c9c2acdbe284..c8d53d737c88 100644 --- a/python/MooseDocs/extensions/civet.py +++ b/python/MooseDocs/extensions/civet.py @@ -208,13 +208,17 @@ class CivetMergeResultsCommand(CivetCommandBase): @staticmethod def defaultSettings(): settings = CivetCommandBase.defaultSettings() + settings['use_current_hash'] = (True, "Use the hash for the current version of the documentation build, otherwise use the most up-to-date hash from the git remote.") return settings def createToken(self, parent, info, page, settings): site, repo = self.getCivetInfo(settings) - - rows = [] - for sha in self.extension.hashes() or list(): + merge_results_hashes = list() + if not settings['use_current_hash']: + merge_results_hashes = self.extension.hashes() + else: + merge_results_hashes = mooseutils.get_civet_hashes(commit=mooseutils.git_commit()) + for sha in merge_results_hashes or list(): url = '{}/sha_events/{}/{}'.format(site, repo, sha) link = core.Link(parent, url=url, string=sha) core.LineBreak(parent) diff --git a/python/doc/content/python/MooseDocs/extensions/civet.md b/python/doc/content/python/MooseDocs/extensions/civet.md new file mode 100644 index 000000000000..82ee79bf1071 --- /dev/null +++ b/python/doc/content/python/MooseDocs/extensions/civet.md @@ -0,0 +1,108 @@ +# CIVET Extension + +The [!ac](CIVET) extension adds the ability for MooseDocs to download results from a [CIVET] client +(e.g., [https://civet.inl.gov](https://civet.inl.gov)) and present them as reports, links, badges, +and other information in a MooseDocs page. This extension is most-often used with the [extensions/sqa.md]. + +## Extension Configuration + +[config-civet-ext] lists the available configuration settings for the CIVET extension. These +configuration items should be included in the MooseDocs configuration file (e.g., config.yml). + +!devel settings id=config-civet-ext + caption=Configuration options for the CIVET extension. + module=MooseDocs.extensions.civet + object=CivetExtension + +## Extension Commands + +The following sections provide information regarding each of the commands available to the extension. + +### Results Inline Linking + +The `results` inline command allows for linking to testing results for the version of the code repository +used to build the documentation. It generates a single link displaying the git commit SHA which links +to the associated CIVET results for that SHA. + +!devel! example id=civet-results-example + caption=Example of the CIVET extension `results` command. + +[!civet!results] + +!devel-end! + +!devel settings id=civet-results + caption=Options for the CIVET extension `results` command. + module=MooseDocs.extensions.civet + object=CivetResultsCommand + +### Merge Results Linking + +The `civet mergeresults` command provides a set of links to CIVET results pages for the version of +the code repository used to build the documentation (by default). This is similar to the [#results-inline-linking] +command, except multiple links are provided. Each link is labeled using the git SHA associated with +the merge event that prompted testing. This means that MOOSE, for example, might have multiple links +associated with `next`, `devel`, and `master` testing events associated with a single `master` branch +merge constituting the current version of the code and documentation. If the `use_current_hash` +settings option is set to `False`, then the most up-to-date version of the these links is retrieved +from the online remote repository. + +!devel! example id=civet-merge-results-example + caption=Example of the CIVET extension `mergeresults` command. + +!civet mergeresults +!devel-end! + +!alert! tip title=Inline usage +Note that this command can also be used inline, using the `[!civet!mergeresults]` syntax. +!alert-end! + +!devel settings id=civet-merge-results + caption=Options for the CIVET extension `mergeresults` command. + module=MooseDocs.extensions.civet + object=CivetMergeResultsCommand + +### Test Results Badges + +The `badges` command allows the display of a badge (or badges) containing the aggregate status of +all tests that were completed corresponding to one or more test specifications for the results +associated with the version of the code repository used to build the documentation. Clicking on the +badge directs the browser to a report page where individual results can be inspected. + +!devel! example id=civet-badges-example + caption=Examples of the CIVET extension `badges` command. + +With one test specification: + +!civet badges tests=kernels/simple_diffusion.test + +With two test specifications: + +!civet badges tests=kernels/simple_diffusion.test outputs/common.exodus + +!devel-end! + +!alert! tip title=Inline usage +Note that this command can also be used inline, using the `[!civet!badges tests=...]` syntax. +!alert-end! + +!devel settings id=civet-badges + caption=Options for the CIVET extension `badges` command. + module=MooseDocs.extensions.civet + object=CivetTestBadgesCommand + +### Test Results Report + +The `report` command generates a table of jobs, associated CIVET recipes, and test statuses for a given test specification. While this command is available for general use within any markdown page, the table generation activity called by this command is generally used within the [#test-results-badges] command, where a results page is generated for linking to the rendered badge. + +!devel! example id=civet-report-example + caption=Example of the CIVET extension `report` command. + +!civet report tests=kernels/simple_diffusion.test + +!devel-end! + +!devel settings id=civet-report + caption=Options for the CIVET extension `report` command. + module=MooseDocs.extensions.civet + object=CivetTestReportCommand diff --git a/python/doc/content/python/MooseDocs/extensions/sqa.md b/python/doc/content/python/MooseDocs/extensions/sqa.md index 00fd98769db9..5325ec306e34 100644 --- a/python/doc/content/python/MooseDocs/extensions/sqa.md +++ b/python/doc/content/python/MooseDocs/extensions/sqa.md @@ -249,7 +249,7 @@ The available options for the "collections" settings are listed below. ## Extension Commands -The following sections provide information regarding each of the +The following sections provide information regarding each of the commands available to the extension. ### Requirement Cross-Reference List diff --git a/python/doc/content/python/MooseDocs/specification.md b/python/doc/content/python/MooseDocs/specification.md index 77d8432ce26d..cfdaff1af36a 100644 --- a/python/doc/content/python/MooseDocs/specification.md +++ b/python/doc/content/python/MooseDocs/specification.md @@ -54,6 +54,7 @@ tables. [user-ext] provides a list of extensions that are useful for those writi | [extensions/media.md] | Extension for including images and movies. | | [extensions/appsyntax.md] | Enables the use of MOOSE application syntax within markdown files. | | [extensions/sqa.md] | Provides tools for writing software quality documentation using templates. | +| [CIVET Extension](extensions/civet.md optional=True) | Provides linking and results connections to [CIVET](https://github.com/idaholab/civet) testing results. | | [extensions/layout.md] | Provides tools for creating columns and tabs via markdown. | | [extensions/acronym.md] | Provides means for defining and listing acronyms across pages. | | [extensions/graph.md] | Adds [plotly](https://plot.ly) support for creating charts. |