-
Notifications
You must be signed in to change notification settings - Fork 1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #16156 from aeslaughter/generate-16155
Improve stub generate command and associated testing
- Loading branch information
Showing
12 changed files
with
335 additions
and
91 deletions.
There are no files selected for viewing
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
# MeshGeneratorMesh | ||
|
||
!alert! construction title=Undocumented Class | ||
The MeshGeneratorMesh has not been documented. The content listed below should be used as a starting point for | ||
documenting the class, which includes the typical automatic documentation associated with a | ||
MooseObject; however, what is contained is ultimately determined by what is necessary to make the | ||
documentation clear for users. | ||
|
||
```markdown | ||
# MeshGeneratorMesh | ||
|
||
!syntax description /Mesh/MeshGeneratorMesh | ||
|
||
## Overview | ||
|
||
!! Replace these lines with information regarding the MeshGeneratorMesh object. | ||
|
||
## Example Input File Syntax | ||
|
||
!! Describe and include an example of how to use the MeshGeneratorMesh object. | ||
|
||
!syntax parameters /Mesh/MeshGeneratorMesh | ||
|
||
!syntax inputs /Mesh/MeshGeneratorMesh | ||
|
||
!syntax children /Mesh/MeshGeneratorMesh | ||
``` | ||
!alert-end! | ||
|
||
!syntax description /Mesh/MeshGeneratorMesh | ||
|
||
!syntax parameters /Mesh/MeshGeneratorMesh | ||
|
||
!syntax inputs /Mesh/MeshGeneratorMesh | ||
|
||
!syntax children /Mesh/MeshGeneratorMesh |
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
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,105 @@ | ||
#* This file is part of the MOOSE framework | ||
#* https://www.mooseframework.org | ||
#* | ||
#* All rights reserved, see COPYRIGHT for full restrictions | ||
#* https://github.com/idaholab/moose/blob/master/COPYRIGHT | ||
#* | ||
#* Licensed under LGPL 2.1, please see LICENSE for details | ||
#* https://www.gnu.org/licenses/lgpl-2.1.html | ||
|
||
"""Developer tools for MooseDocs.""" | ||
import argparse | ||
import os | ||
import re | ||
import collections | ||
import logging | ||
|
||
import MooseDocs | ||
import moosesqa | ||
import moosetree | ||
import mooseutils | ||
import moosesyntax | ||
|
||
from .. import common | ||
from ..extensions import template | ||
|
||
LOG = logging.getLogger(__name__) | ||
|
||
def command_line_options(subparser, parent): | ||
"""Define the 'generate' command.""" | ||
parser = subparser.add_parser('generate', | ||
parents=[parent], | ||
help="Tool for creating/updating documentation stub pages.") | ||
parser.add_argument('app_types', nargs='+', type=str, | ||
help="A list of app types to use when generate stub pages (e.g., StochasticToolsApp).") | ||
parser.add_argument('--config', type=str, default='sqa_reports.yml', | ||
help="The YAML config file for performing SQA checks.") | ||
|
||
def main(opt): | ||
"""./moosedocs generate""" | ||
|
||
# Setup logging | ||
logger = logging.getLogger('MooseDocs') | ||
logger.handlers = list() | ||
logger.addHandler(moosesqa.SilentRecordHandler()) | ||
|
||
# Get the report objects for the applications | ||
_, _, app_reports = moosesqa.get_sqa_reports(opt.config, app_report=True, doc_report=False, req_report=False) | ||
|
||
# Loop through all reports and generate the stub pages | ||
for report in app_reports: | ||
report.app_types = opt.app_types | ||
report.getReport() # this is needed to generate the app syntax | ||
for node in moosetree.iterate(report.app_syntax, lambda n: _shouldCreateStub(report, n)): | ||
_createStubPage(report, node) | ||
|
||
logger.handlers[0].clear() # don't report errors, that is the job for check command | ||
return 0 | ||
|
||
def _shouldCreateStub(report, n): | ||
return (not n.removed) \ | ||
and ('_md_file' in n) \ | ||
and ((n['_md_file'] is None) or n['_is_stub']) \ | ||
and ((n.group in report.app_types) \ | ||
or (n.groups() == set(report.app_types))) | ||
|
||
def _createStubPage(report, node): | ||
"""Copy template content to expected document location.""" | ||
|
||
# Determine the correct markdown filename | ||
filename = node['_md_path'] | ||
if isinstance(node, moosesyntax.ObjectNodeBase): | ||
filename = os.path.join(report.working_dir, node['_md_path']) | ||
elif isinstance(node, moosesyntax.SyntaxNode): | ||
action = moosetree.find(node, lambda n: isinstance(n, moosesyntax.ActionNode)) | ||
filename = os.path.join(report.working_dir,os.path.dirname(node['_md_path']), 'index.md') | ||
|
||
# Determine the source template | ||
tname = None | ||
if isinstance(node, moosesyntax.SyntaxNode): | ||
tname = 'moose_system.md.template' | ||
elif isinstance(node, moosesyntax.MooseObjectNode): | ||
tname = 'moose_object.md.template' | ||
elif isinstance(node, moosesyntax.ActionNode): | ||
tname = 'moose_action.md.template' | ||
else: | ||
raise Exception("Unexpected syntax node type.") | ||
|
||
# Template file | ||
tname = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', '..', 'framework', | ||
'doc', 'content','templates', 'stubs', tname)) | ||
|
||
# Read template and apply node content | ||
with open(tname, 'r') as fid: | ||
content = fid.read() | ||
content = mooseutils.apply_template_arguments(content, name=node.name, syntax=node.fullpath()) | ||
|
||
# Write the content to the desired destination | ||
print("Creating/updating stub page: {}".format(filename)) | ||
_writeFile(filename, content) | ||
|
||
def _writeFile(filename, content): | ||
"""A helper function that is easy to mock in tests""" | ||
os.makedirs(os.path.dirname(filename), exist_ok=True) | ||
with open(filename, 'w') as fid: | ||
fid.write(content) |
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,55 @@ | ||
#* This file is part of the MOOSE framework | ||
#* https://www.mooseframework.org | ||
#* | ||
#* All rights reserved, see COPYRIGHT for full restrictions | ||
#* https://github.com/idaholab/moose/blob/master/COPYRIGHT | ||
#* | ||
#* Licensed under LGPL 2.1, please see LICENSE for details | ||
#* https://www.gnu.org/licenses/lgpl-2.1.html | ||
|
||
"""Developer tools for MooseDocs.""" | ||
import argparse | ||
import os | ||
import re | ||
import collections | ||
import logging | ||
|
||
import MooseDocs | ||
import moosesqa | ||
import moosetree | ||
import mooseutils | ||
import moosesyntax | ||
|
||
from .. import common | ||
#from ..common import exceptions | ||
#from ..tree import syntax | ||
from ..extensions import template | ||
|
||
LOG = logging.getLogger(__name__) | ||
|
||
def command_line_options(subparser, parent): | ||
"""Define the 'syntax' command.""" | ||
parser = subparser.add_parser('syntax', | ||
parents=[parent], | ||
help="Tool for dumping application syntax to screen.") | ||
parser.add_argument('--config', type=str, default='sqa_reports.yml', | ||
help="The YAML config file for performing SQA checks.") | ||
|
||
def main(opt): | ||
"""./moosedocs syntax""" | ||
|
||
# Setup logging | ||
logger = logging.getLogger('MooseDocs') | ||
logger.handlers = list() | ||
logger.addHandler(moosesqa.SilentRecordHandler()) | ||
|
||
# Get the report objects for the applications | ||
_, _, app_reports = moosesqa.get_sqa_reports(opt.config, app_report=True, doc_report=False, req_report=False) | ||
|
||
# Loop through all reports and generate the stub pages | ||
for report in app_reports: | ||
report.getReport() # this is needed to generate the app syntax | ||
print(report.app_syntax) | ||
|
||
logger.handlers[0].clear() # don't report errors, that is the job for check command | ||
return 0 |
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
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
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,60 @@ | ||
#!/usr/bin/env python3 | ||
#* This file is part of the MOOSE framework | ||
#* https://www.mooseframework.org | ||
#* | ||
#* All rights reserved, see COPYRIGHT for full restrictions | ||
#* https://github.com/idaholab/moose/blob/master/COPYRIGHT | ||
#* | ||
#* Licensed under LGPL 2.1, please see LICENSE for details | ||
#* https://www.gnu.org/licenses/lgpl-2.1.html | ||
import os | ||
import unittest | ||
import mock | ||
import types | ||
import io | ||
import mooseutils | ||
import moosesqa | ||
from MooseDocs.commands import generate | ||
|
||
@unittest.skipIf(mooseutils.git_version() < (2,11,4), "Git version must at least 2.11.4") | ||
class TestGenerate(unittest.TestCase): | ||
def setUp(self): | ||
# Change to the test/doc directory | ||
self._working_dir = os.getcwd() | ||
moose_test_doc_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', '..', '..', 'test', 'doc')) | ||
os.chdir(moose_test_doc_dir) | ||
|
||
def tearDown(self): | ||
# Restore the working directory | ||
os.chdir(self._working_dir) | ||
|
||
@mock.patch('MooseDocs.commands.generate._shouldCreateStub') | ||
@mock.patch('MooseDocs.commands.generate._writeFile') | ||
def testGenerate(self, writeFile, shouldCreateStub): | ||
|
||
# Store the filenames to be created | ||
filenames = list() | ||
writeFile.side_effect = lambda fn, *args: filenames.append(fn) | ||
|
||
# Create custom function for determining if a stub should be created | ||
shouldCreateStub.side_effect = self._shouldCreateStub | ||
|
||
# Run the generate command | ||
opt = types.SimpleNamespace(app_types=['MooseApp'], config='sqa_test_reports.yml') | ||
status = generate.main(opt) | ||
|
||
self.assertEqual(status, 0) | ||
self.assertEqual(len(filenames), 3) | ||
self.assertTrue(filenames[0].endswith('moose/test/doc/content/syntax/Kernels/index.md')) | ||
self.assertTrue(filenames[1].endswith('moose/test/doc/content/source/actions/AddKernelAction.md')) | ||
self.assertTrue(filenames[2].endswith('moose/test/doc/content/source/kernels/Diffusion.md')) | ||
|
||
@staticmethod | ||
def _shouldCreateStub(report, n): | ||
# Test for stub on Action, Object, and Syntax | ||
if n.fullpath() in ('/Kernels/AddKernelAction', '/Kernels/Diffusion', '/Kernels'): | ||
return True | ||
return False | ||
|
||
if __name__ == '__main__': | ||
unittest.main(verbosity=2) |
Oops, something went wrong.