def generate(config_file='moosedocs.yml', pages='pages.yml', stubs=False, pages_stubs=False, **kwargs):
"""
Generates MOOSE system and object markdown files from the source code.
Args:
config_file[str]: (Default: 'moosedocs.yml') The MooseMkDocs project configuration file.
"""
# Configuration file
if not os.path.exists(config_file):
raise IOError("The supplied configuration file was not found: {}".format(config_file))
# Read the configuration
config = MooseDocs.yaml_load(config_file)
config = config['markdown_extensions'][-1]['MooseDocs.extensions.MooseMarkdown']
# Run the executable
exe = config['executable']
if not os.path.exists(exe):
log.error('The executable does not exist: {}'.format(exe))
else:
log.debug("Executing {} to extract syntax.".format(exe))
raw = utils.runExe(exe, '--yaml')
yaml = utils.MooseYaml(raw)
# Populate the syntax
for key, value in config['locations'].iteritems():
if 'hide' in value:
value['hide'] += config.get('hide', [])
else:
value['hide'] = config.get('hide', [])
syntax = MooseDocs.MooseApplicationSyntax(yaml, name=key, stubs=stubs, pages_stubs=pages_stubs, pages=pages, **value)
log.info("Checking documentation for '{}'.".format(key))
syntax.check()
def execute(self, exe):
"""
Execute the supplied MOOSE application and return the YAML.
Args:
exe[str]: The MOOSE executable.
"""
if not (exe or os.path.exists(exe)):
log.error('The executable does not exist: {}'.format(exe))
else:
log.debug("Executing {} to extract syntax.".format(exe))
try:
raw = utils.runExe(exe, '--yaml')
return utils.MooseYaml(raw)
except:
log.error('Failed to read YAML file, MOOSE and modules are likely not compiled correctly.')
sys.exit(1);
def generate(config_file='moosedocs.yml',
pages='pages.yml',
stubs=False,
pages_stubs=False,
**kwargs):
"""
Generates MOOSE system and object markdown files from the source code.
Args:
config_file[str]: (Default: 'moosedocs.yml') The MooseMkDocs project configuration file.
"""
# Configuration file
if not os.path.exists(config_file):
raise IOError(
"The supplied configuration file was not found: {}".format(
config_file))
# Read the configuration
config = MooseDocs.yaml_load(config_file)
config = config['markdown_extensions'][-1][
'MooseDocs.extensions.MooseMarkdown']
# Run the executable
exe = config['executable']
if not os.path.exists(exe):
log.error('The executable does not exist: {}'.format(exe))
else:
log.debug("Executing {} to extract syntax.".format(exe))
raw = utils.runExe(exe, '--yaml')
yaml = utils.MooseYaml(raw)
# Populate the syntax
for key, value in config['locations'].iteritems():
if 'hide' in value:
value['hide'] += config['hide']
else:
value['hide'] = config['hide']
syntax = MooseDocs.MooseApplicationSyntax(yaml,
name=key,
stubs=stubs,
pages_stubs=pages_stubs,
pages=pages,
**value)
log.info("Checking documentation for '{}'.".format(key))
syntax.check()
def generate(self):
"""
Generate the documentation.
"""
# Setup the location
log.info('Generating Documentation: {}'.format(self._config_file))
# Parse the configuration file for the desired paths
configs = self._configure()
# Locate and run the MOOSE executable
raw = utils.runExe(self._exe, '--yaml')
ydata = utils.MooseYaml(raw)
for config in configs:
generator = MooseSubApplicationDocGenerator(ydata, config)
generator.write()
def _generate(self):
"""
Generate the documentation.
"""
# Setup the location
log.info('Generating Documentation: {}'.format(self._config_file))
# Parse the configuration file for the desired paths
configs = self._configure()
# Locate and run the MOOSE executable
raw = utils.runExe(self._exe, '--yaml')
ydata = utils.MooseYaml(raw)
for config in configs:
generator = MooseSubApplicationDocGenerator(ydata, config)
generator.write()
# Create the mkdocs.yml file
# TODO: When mkdocs plugins API is up and running this should go away.
def dumptree(node, level=0):
for item in node:
for key, value in item.iteritems():
if isinstance(value, list):
yield '{}- {}:'.format(' '*4*level, key)
for f in dumptree(value, level+1):
yield f
else:
yield '{}- {}: {}'.format(' '*4*(level), key, value)
pages = MooseDocs.yaml_load('pages.yml')
output = ['pages:']
output += dumptree(pages, 1)
shutil.copyfile('mkdocs.template.yml', 'mkdocs.yml')
with open('mkdocs.yml', 'a') as fid:
fid.write('\n'.join(output))
def extendMarkdown(self, md, md_globals):
"""
Builds the extensions for MOOSE flavored markdown.
"""
# Strip description from config
config = self.getConfigs()
# Generate YAML data from application
global cache
exe = config['executable']
if exe != cache['exe']:
if not os.path.exists(exe):
log.error('The executable does not exist: {}'.format(exe))
else:
log.debug("Executing {} to extract syntax.".format(exe))
raw = utils.runExe(exe, '--yaml')
cache['exe'] = exe
cache['yaml'] = utils.MooseYaml(raw)
# Populate auto-link database
if not cache['markdown_include']:
log.info('Building markdown database for auto links.')
loc = os.path.join(self.config['root'][0],
self.config['docs_dir'][0])
cache['markdown_include'] = MooseDocs.database.Database(
'.md', loc, MooseDocs.database.items.MarkdownIncludeItem)
# Populate the database for input file and children objects
if not cache['input_files']:
log.info('Building input and inheritance databases...')
for key, path in config['links'].iteritems():
cache['input_files'][key] = MooseDocs.database.Database(
'.i',
path,
MooseDocs.database.items.InputFileItem,
repo=config['repo'])
cache['child_objects'][key] = MooseDocs.database.Database(
'.h',
path,
MooseDocs.database.items.ChildClassItem,
repo=config['repo'])
# Populate the syntax
if not cache['syntax']:
for key, value in config['locations'].iteritems():
cache['syntax'][key] = MooseDocs.MooseApplicationSyntax(
cache['yaml'], **value)
# Preprocessors
md.preprocessors.add(
'moose_auto_link',
MooseMarkdownLinkPreprocessor(markdown_instance=md,
database=cache['markdown_include']),
'_begin')
if config['slides']:
md.preprocessors.add('moose_slides',
MooseSlidePreprocessor(markdown_instance=md),
'_end')
# Block processors
md.parser.blockprocessors.add(
'diagrams', MooseDiagram(md.parser, graphviz=config['graphviz']),
'_begin')
md.parser.blockprocessors.add(
'slideshow', MooseCarousel(md.parser, root=config['root']),
'_begin')
md.parser.blockprocessors.add('css',
MooseCSS(md.parser, root=config['root']),
'_begin')
# Inline Patterns
object_markdown = MooseObjectSyntax(
markdown_instance=md,
yaml=cache['yaml'],
syntax=cache['syntax'],
input_files=cache['input_files'],
child_objects=cache['child_objects'],
repo=config['repo'],
root=config['root'])
system_markdown = MooseSystemSyntax(markdown_instance=md,
yaml=cache['yaml'],
syntax=cache['syntax'])
md.inlinePatterns.add('moose_object_syntax', object_markdown, '_begin')
md.inlinePatterns.add('moose_system_syntax', system_markdown, '_begin')
md.inlinePatterns.add(
'moose_input_block',
MooseInputBlock(markdown_instance=md,
repo=config['repo'],
root=config['root']), '<image_link')
md.inlinePatterns.add(
'moose_cpp_method',
MooseCppMethod(markdown_instance=md,
make=config['make'],
repo=config['repo'],
root=config['root']), '<image_link')
md.inlinePatterns.add(
'moose_text',
MooseTextFile(markdown_instance=md,
repo=config['repo'],
root=config['root']), '<image_link')
md.inlinePatterns.add(
'moose_image',
MooseImageFile(markdown_instance=md, root=config['root']),
'<image_link')
md.inlinePatterns.add('moose_build_status',
MooseBuildStatus(markdown_instance=md), '_begin')
if config['package']:
md.inlinePatterns.add('moose_package_parser',
MoosePackageParser(markdown_instance=md),
'_end')
def extendMarkdown(self, md, md_globals):
"""
Builds the extensions for MOOSE flavored markdown.
"""
# Strip description from config
config = self.getConfigs()
# Generate YAML data from application
global cache
exe = config['executable']
if exe != cache['exe']:
if not os.path.exists(exe):
log.error('The executable does not exist: {}'.format(exe))
else:
log.debug("Executing {} to extract syntax.".format(exe))
raw = utils.runExe(exe, '--yaml')
cache['exe'] = exe
cache['yaml'] = utils.MooseYaml(raw)
# Populate the database for input file and children objects
if not cache['input_files']:
log.info('Building input and inheritance databases...')
for key, path in config['links'].iteritems():
cache['input_files'][key] = MooseDocs.database.Database('.i', path, MooseDocs.database.items.InputFileItem, repo=config['repo'])
cache['child_objects'][key] = MooseDocs.database.Database('.h', path, MooseDocs.database.items.ChildClassItem, repo=config['repo'])
# Populate the syntax
if not cache['syntax']:
for key, value in config['locations'].iteritems():
cache['syntax'][key] = MooseDocs.MooseApplicationSyntax(cache['yaml'], **value)
# Populate the pages yaml
if not cache['pages']:
yml = MooseDocs.yaml_load(config['pages'])
for match in re.finditer(r':(.*?\.md)', yaml.dump(yml, default_flow_style=False)):
cache['pages'].append(match.group(1).strip())
# Preprocessors
md.preprocessors.add('moose_bibtex', MooseBibtex(markdown_instance=md, root=config['root']), '_end')
md.preprocessors.add('moose_auto_link', MooseMarkdownLinkPreprocessor(markdown_instance=md, pages=cache['pages']), '_begin')
if config['slides']:
md.preprocessors.add('moose_slides', MooseSlidePreprocessor(markdown_instance=md), '_end')
# Block processors
md.parser.blockprocessors.add('diagrams', MooseDiagram(md.parser, graphviz=config['graphviz']), '_begin')
md.parser.blockprocessors.add('slideshow', MooseCarousel(md.parser, root=config['root']), '_begin')
md.parser.blockprocessors.add('css', MooseCSS(md.parser, root=config['root']), '_begin')
# Inline Patterns
object_markdown = MooseObjectSyntax(markdown_instance=md,
yaml=cache['yaml'],
syntax=cache['syntax'],
input_files=cache['input_files'],
child_objects=cache['child_objects'],
repo=config['repo'],
root=config['root'])
system_markdown = MooseSystemSyntax(markdown_instance=md,
yaml=cache['yaml'],
syntax=cache['syntax'])
md.inlinePatterns.add('moose_object_syntax', object_markdown, '_begin')
md.inlinePatterns.add('moose_system_syntax', system_markdown, '_begin')
md.inlinePatterns.add('moose_input_block', MooseInputBlock(markdown_instance=md, repo=config['repo'], root=config['root']), '<image_link')
md.inlinePatterns.add('moose_cpp_method', MooseCppMethod(markdown_instance=md, make=config['make'], repo=config['repo'], root=config['root']), '<image_link')
md.inlinePatterns.add('moose_text', MooseTextFile(markdown_instance=md, repo=config['repo'], root=config['root']), '<image_link')
md.inlinePatterns.add('moose_image', MooseImageFile(markdown_instance=md, root=config['root']), '<image_link')
md.inlinePatterns.add('moose_build_status', MooseBuildStatus(markdown_instance=md), '_begin')
if config['package']:
md.inlinePatterns.add('moose_package_parser', MoosePackageParser(markdown_instance=md), '_end')
def extendMarkdown(self, md, md_globals):
"""
Builds the extensions for MOOSE flavored markdown.
"""
# Strip description from config
config = self.getConfigs()
# Generate YAML data from application
global cache
exe = config['executable']
if exe != cache['exe']:
if not os.path.exists(exe):
log.error('The executable does not exist: {}'.format(exe))
else:
log.debug("Executing {} to extract syntax.".format(exe))
raw = utils.runExe(exe, '--yaml')
cache['exe'] = exe
cache['yaml'] = utils.MooseYaml(raw)
# Populate the database for input file and children objects
if not cache['input_files']:
log.info('Building input and inheritance databases...')
for key, path in config['links'].iteritems():
cache['input_files'][key] = MooseDocs.database.Database(
'.i',
path,
MooseDocs.database.items.InputFileItem,
repo=config['repo'])
cache['child_objects'][key] = MooseDocs.database.Database(
'.h',
path,
MooseDocs.database.items.ChildClassItem,
repo=config['repo'])
# Populate the syntax
if not cache['syntax']:
for key, value in config['locations'].iteritems():
if 'hide' in value:
value['hide'] += config['hide']
else:
value['hide'] = config['hide']
cache['syntax'][key] = MooseDocs.MooseApplicationSyntax(
cache['yaml'], **value)
# Populate the pages yaml
if not cache['pages']:
yml = MooseDocs.yaml_load(config['pages'])
for match in re.finditer(r':(.*?\.md)',
yaml.dump(yml, default_flow_style=False)):
cache['pages'].append(match.group(1).strip())
# Preprocessors
bibtex = MooseBibtex(markdown_instance=md, root=config['root'])
md.preprocessors.add('moose_bibtex', bibtex, '_end')
links = MooseMarkdownLinkPreprocessor(markdown_instance=md,
pages=cache['pages'])
md.preprocessors.add('moose_auto_link', links, '_begin')
if config['slides']:
slides = MooseSlidePreprocessor(markdown_instance=md)
md.preprocessors.add('moose_slides', slides, '_end')
# Block processors
diagrams = MooseDiagram(md.parser,
root=config['root'],
docs_dir=config['docs_dir'],
graphviz=config['graphviz'],
ext=config['dot_ext'])
md.parser.blockprocessors.add('diagrams', diagrams, '_begin')
carousel = MooseCarousel(md.parser,
root=config['root'],
docs_dir=config['docs_dir'])
md.parser.blockprocessors.add('slideshow', carousel, '_begin')
css = MooseCSS(md.parser,
root=config['root'],
docs_dir=config['docs_dir'])
md.parser.blockprocessors.add('css', css, '_begin')
# Inline Patterns
object_markdown = MooseObjectSyntax(
markdown_instance=md,
yaml=cache['yaml'],
syntax=cache['syntax'],
input_files=cache['input_files'],
child_objects=cache['child_objects'],
repo=config['repo'],
root=config['root'],
docs_dir=config['docs_dir'])
md.inlinePatterns.add('moose_object_syntax', object_markdown, '_begin')
system_markdown = MooseSystemSyntax(markdown_instance=md,
yaml=cache['yaml'],
syntax=cache['syntax'],
root=config['root'],
docs_dir=config['docs_dir'])
md.inlinePatterns.add('moose_system_syntax', system_markdown, '_begin')
moose_input = MooseInputBlock(markdown_instance=md,
root=config['root'],
docs_dir=config['docs_dir'],
repo=config['repo'])
md.inlinePatterns.add('moose_input_block', moose_input, '<image_link')
moose_cpp = MooseCppMethod(markdown_instance=md,
root=config['root'],
docs_dir=config['docs_dir'],
make=config['make'],
repo=config['repo'])
md.inlinePatterns.add('moose_cpp_method', moose_cpp, '<image_link')
moose_text = MooseTextFile(markdown_instance=md,
root=config['root'],
docs_dir=config['docs_dir'],
repo=config['repo'])
md.inlinePatterns.add('moose_text', moose_text, '<image_link')
moose_image = MooseImageFile(markdown_instance=md,
root=config['root'],
docs_dir=config['docs_dir'])
md.inlinePatterns.add('moose_image', moose_image, '<image_link')
moose_status = MooseBuildStatus(markdown_instance=md,
root=config['root'],
docs_dir=config['docs_dir'])
md.inlinePatterns.add('moose_build_status', moose_status, '_begin')
if config['package']:
package = MoosePackageParser(markdown_instance=md,
root=config['root'],
docs_dir=config['docs_dir'])
md.inlinePatterns.add('moose_package_parser', package, '_end')