From 15ffbc0bd87a6d4a9590ca23f08c38d3ced72878 Mon Sep 17 00:00:00 2001 From: "Icenhour, Casey Tyler" Date: Tue, 17 Dec 2024 16:23:20 -0700 Subject: [PATCH] Change default for MooseDocs CIVET mergeresults command The command will now always look to the current git commit SHA to determine the linked CI results by default. The old behavior is available using use_current_hash=False in the command. This commit also adds documentation for MooseDocs CIVET extension Refs #29565 --- framework/doc/globals.yml | 1 + python/MooseDocs/extensions/civet.py | 10 +- .../python/MooseDocs/extensions/civet.md | 108 ++++++++++++++++++ .../python/MooseDocs/extensions/sqa.md | 2 +- .../content/python/MooseDocs/specification.md | 1 + 5 files changed, 118 insertions(+), 4 deletions(-) create mode 100644 python/doc/content/python/MooseDocs/extensions/civet.md 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/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..930061779120 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. | +| [extensions/civet.md] | 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. |