def setUpClass(cls):
"""
Create the markdown parser using the configuration file.
"""
super(MarkdownTestCase, cls).setUpClass()
# Setup logging
cls._stream = StringIO.StringIO()
cls._formatter = init_logging(stream=cls._stream)
# Define the local directory
cls._path = os.path.abspath(os.path.dirname(inspect.getfile(cls)))
# Read the YAML configurations
config = MooseMarkdown.getDefaultExtensions()
config.update(MooseDocs.load_config(os.path.join(MooseDocs.MOOSE_DIR, 'docs', cls.CONFIG)))
# Update extension list
if cls.EXTENSIONS:
for key in config:
if key not in cls.EXTENSIONS:
config.pop(key)
cls.updateExtensions(config)
cls.parser = MooseMarkdown(config, default=False)
def setUpClass(cls):
"""
Create the markdown parser using the configuration file.
"""
super(MarkdownTestCase, cls).setUpClass()
# Setup logging
cls._stream = StringIO.StringIO()
cls._formatter = init_logging(stream=cls._stream)
# Define the local directory
cls._path = os.path.abspath(os.path.dirname(inspect.getfile(cls)))
# Read the YAML configurations
config = MooseMarkdown.getDefaultExtensions()
config.update(
MooseDocs.load_config(
os.path.join(MooseDocs.MOOSE_DIR, 'docs', cls.CONFIG)))
# Update extension list
if cls.EXTENSIONS:
for key in config:
if key not in cls.EXTENSIONS:
config.pop(key)
cls.updateExtensions(config)
cls.parser = MooseMarkdown(config, default=False)
def check(config_file=None, locations=None, generate=None):
"""
Performs checks and optionally generates stub pages for missing documentation.
"""
# Read the configuration
app_ext = 'MooseDocs.extensions.app_syntax'
config = MooseDocs.load_config(config_file)
if app_ext not in config:
mooseutils.MooseException("The 'check' utility requires the 'app_syntax' extension.")
ext_config = config[app_ext]
# Run the executable
exe = MooseDocs.abspath(ext_config['executable'])
if not os.path.exists(exe):
raise IOError('The executable does not exist: {}'.format(exe))
else:
LOG.debug("Executing %s to extract syntax.", exe)
raw = mooseutils.runExe(exe, '--yaml')
yaml = mooseutils.MooseYaml(raw)
# Populate the syntax
for loc in ext_config['locations']:
for key, value in loc.iteritems():
if (locations is None) or (key in locations):
value['group'] = key
syntax = common.MooseApplicationSyntax(yaml, generate=generate,
install=ext_config['install'], **value)
LOG.info("Checking documentation for '%s'.", key)
syntax.check()
return None
def setUpClass(cls):
"""
Create link database.
"""
config = MooseDocs.load_config(os.path.join(MooseDocs.MOOSE_DIR, 'docs', 'website.yml'))
options = config['MooseDocs.extensions.app_syntax']
cls.database = MooseLinkDatabase(repo=options['repo'], links=options['links'])
def presentation(config_file=None, md_file=None, serve=None, port=None, host=None, template=None,
**template_args):
"""
MOOSE markdown presentation blaster.
"""
# The markdown file is provided via the command line, thus it is provided relative to the
# current working directory. The internals of MooseDocs are setup to always work from the
# repository root directory (i.e., MooseDocs.ROOT_DIR), thus the path of this file must be
# converted to be relative to MooseDocs.ROOT_DIR.
md_file = os.path.relpath(os.path.abspath(md_file), MooseDocs.ROOT_DIR)
# Create the markdown parser
config = MooseDocs.load_config(config_file, template=template, template_args=template_args)
parser = MooseMarkdown(config)
# Build the html
builder = PresentationBuilder(md_file=md_file, parser=parser)
builder.init()
builder.build(num_threads=1)
if serve:
server = livereload.Server()
server.watch(os.path.join(MooseDocs.ROOT_DIR, md_file),
lambda: builder.build(num_threads=1))
server.serve(root=builder.rootDirectory(), host=host, port=port, restart_delay=0)
return 0
def presentation(config_file=None,
md_file=None,
serve=None,
port=None,
host=None,
template=None,
**template_args):
"""
MOOSE markdown presentation blaster.
"""
# Load the YAML configuration file
config = MooseDocs.load_config(config_file,
template=template,
template_args=template_args)
parser = MooseDocs.MooseMarkdown(extensions=config.keys(),
extension_configs=config)
site_dir, _ = os.path.splitext(md_file)
if not os.path.isdir(site_dir):
os.mkdir(site_dir)
root = PresentationBuilder(name='',
markdown=md_file,
parser=parser,
site_dir=site_dir)
root.build()
if serve:
server = livereload.Server()
server.watch(md_file, root.build)
server.serve(root=site_dir, host=host, port=port, restart_delay=0)
return None
def setUpClass(cls):
config = MooseDocs.load_config(
os.path.join(MooseDocs.MOOSE_DIR, 'docs', 'moosedocs.yml'))
options = config['markdown_extensions'][6][
'MooseDocs.extensions.MooseMarkdown']
cls.database = MooseDocs.MooseLinkDatabase(**options)
def check(config_file=None,
generate=None,
update=None,
dump=None,
template=None,
groups=None,
**template_args):
"""
Performs checks and optionally generates stub pages for missing documentation.
"""
# Create the markdown parser and get the AppSyntaxExtension
config = MooseDocs.load_config(config_file,
template=template,
template_args=template_args)
parser = MooseMarkdown(config)
ext = parser.getExtension(AppSyntaxExtension)
syntax = ext.getMooseAppSyntax()
# Dump the complete syntax tree if desired
if dump:
print syntax
# Check all nodes for documentation
for node in syntax.findall():
node.check(ext.getConfig('install'),
generate=generate,
groups=groups,
update=update)
return 0
def setUpClass(cls):
"""
Create link database.
"""
config = MooseDocs.load_config(os.path.join(MooseDocs.MOOSE_DIR, 'docs', 'website.yml'))
options = config['MooseDocs.extensions.app_syntax']
cls.database = MooseLinkDatabase(repo=options['repo'], links=options['links'])
def presentation(config_file=None, md_file=None, serve=None, port=None, host=None, template=None,
**template_args):
"""
MOOSE markdown presentation blaster.
"""
# The markdown file is provided via the command line, thus it is provided relative to the
# current working directory. The internals of MooseDocs are setup to always work from the
# repository root directory (i.e., MooseDocs.ROOT_DIR), thus the path of this file must be
# converted to be relative to MooseDocs.ROOT_DIR.
md_file = os.path.relpath(os.path.abspath(md_file), MooseDocs.ROOT_DIR)
# Create the markdown parser
config = MooseDocs.load_config(config_file, template=template, template_args=template_args)
parser = MooseMarkdown(config)
# Build the html
builder = PresentationBuilder(md_file=md_file, parser=parser)
builder.init()
builder.build(num_threads=1)
if serve:
server = livereload.Server()
server.watch(os.path.join(MooseDocs.ROOT_DIR, md_file),
lambda: builder.build(num_threads=1))
server.serve(root=builder.rootDirectory(), host=host, port=port, restart_delay=0)
return 0
def latex(config_file=None,
output=None,
md_file=None,
template=None,
**template_args):
"""
Command for converting markdown file to latex.
"""
LOG.warning(
"The latex command is experimental and requires additional development to be "
"complete, please be patient as this develops.\nIf you would like to aid in "
"improving this feature please contact the MOOSE mailing list: "
"[email protected].")
# The markdown file is provided via the command line, thus it is provided relative to the
# current working directory. The internals of MooseDocs are setup to always work from the
# repository root directory (i.e., MooseDocs.ROOT_DIR), thus the path of this file must be
# converted to be relative to MooseDocs.ROOT_DIR.
md_file = os.path.relpath(os.path.abspath(md_file), MooseDocs.ROOT_DIR)
# Create the markdown parser
config = MooseDocs.load_config(config_file,
template=template,
template_args=template_args)
parser = MooseMarkdown(config)
# Build the html
builder = LatexBuilder(md_file=md_file, output=output, parser=parser)
builder.init()
builder.build(num_threads=1)
return 0
def build(config_file=None,
site_dir=None,
num_threads=None,
no_livereload=False,
content=None,
dump=False,
clean=False,
serve=False,
host=None,
port=None,
template=None,
**template_args):
"""
The main build command.
"""
if serve:
clean = True
site_dir = os.path.abspath(os.path.join(MooseDocs.TEMP_DIR, 'site'))
# Clean/create site directory
if clean and os.path.exists(site_dir):
LOG.info('Cleaning build directory: %s', site_dir)
shutil.rmtree(site_dir)
# Create the "temp" directory
if not os.path.exists(site_dir):
os.makedirs(site_dir)
# Create the markdown parser
config = MooseDocs.load_config(config_file,
template=template,
template_args=template_args)
parser = MooseMarkdown(config)
# Create the builder object and build the pages
builder = WebsiteBuilder(parser=parser, site_dir=site_dir, content=content)
builder.init()
if dump:
print builder
return None
builder.build(num_threads=num_threads)
# Serve
if serve:
if not no_livereload:
server = livereload.Server(
watcher=MooseDocsWatcher(builder, num_threads))
else:
server = livereload.Server()
server.serve(root=site_dir, host=host, port=port, restart_delay=0)
return 0
def latex(config_file=None, output=None, md_file=None, **kwargs):
"""
Command for converting markdown file to latex.
"""
# Load the YAML configuration file
config = MooseDocs.load_config(config_file, **kwargs)
parser = MooseDocs.MooseMarkdown(extensions=config.keys(), extension_configs=config)
site_dir, _ = os.path.splitext(md_file)
root = LatexBuilder(output, name='', markdown=md_file, parser=parser, site_dir=site_dir)
root.build()
return None
def generate_html(md_file, config_file):
"""
Generates html from Moose flavored markdown.
Args:
md_file[str]: The *.md file or text to convert.
config_file[str]: The *.yml configuration file.
"""
# Load the YAML configuration file
config = MooseDocs.load_config(config_file)
# Create the markdown parser
extensions, extension_configs = MooseDocs.get_markdown_extensions(config)
parser = markdown.Markdown(extensions=extensions, extension_configs=extension_configs)
# Read and parse the markdown
md, settings = MooseDocs.read_markdown(md_file)
return parser.convert(md), settings
def setUpClass(cls):
# Read the configuration
config = MooseDocs.load_config(
os.path.join(MooseDocs.MOOSE_DIR, 'docs', 'website.yml'))
options = config['MooseDocs.extensions.app_syntax']
# Extract the MOOSE YAML data
exe = os.path.join(MooseDocs.MOOSE_DIR, 'modules', 'combined',
'combined-opt')
raw = mooseutils.runExe(exe, '--yaml')
cls._yaml = mooseutils.MooseYaml(raw)
# Extract the 'framework' location options and build the syntax object
framework = options['locations'][0]['framework']
framework['group'] = 'framework'
framework['install'] = options['install']
framework['hide'] = ['/AuxKernels'] # use to test hide
cls._syntax = MooseApplicationSyntax(cls._yaml, **framework)
def setUpClass(cls):
"""
Create the markdown parser using the 'moosedocs.yml' configuration file.
"""
# Define the local directory
cls._path = os.path.abspath(os.path.dirname(inspect.getfile(cls)))
# Create the markdown object
cwd = os.getcwd()
os.chdir(os.path.join(MooseDocs.MOOSE_DIR, 'docs'))
config = MooseDocs.load_config('moosedocs.yml')
extensions, extension_configs = MooseDocs.get_markdown_extensions(
config)
cls.updateExtensionConfigs(extension_configs)
cls.parser = markdown.Markdown(extensions=extensions,
extension_configs=extension_configs)
os.chdir(cwd)
def check(config_file=None, generate=None, update=None, dump=None, template=None, groups=None,
**template_args):
"""
Performs checks and optionally generates stub pages for missing documentation.
"""
# Create the markdown parser and get the AppSyntaxExtension
config = MooseDocs.load_config(config_file, template=template, template_args=template_args)
parser = MooseMarkdown(config)
ext = parser.getExtension(AppSyntaxExtension)
syntax = ext.getMooseAppSyntax()
# Dump the complete syntax tree if desired
if dump:
print syntax
# Check all nodes for documentation
for node in syntax.findall():
node.check(ext.getConfig('install'), generate=generate, groups=groups, update=update)
return 0
def build_site(config_file='moosedocs.yml',
num_threads=multiprocessing.cpu_count(),
**kwargs):
"""
The main build command.
"""
# Load the YAML configuration file
config = MooseDocs.load_config(config_file, **kwargs)
# Create the markdown parser
extensions, extension_configs = MooseDocs.get_markdown_extensions(config)
parser = markdown.Markdown(extensions=extensions,
extension_configs=extension_configs)
# Create object for storing pages to be generated
builder = Builder(parser, config['site_dir'], config['template'],
config['template_arguments'], config['navigation'])
# Create the html
builder.build(num_threads=num_threads)
return config, parser, builder
def setUpClass(cls):
"""
Create the markdown parser using the configuration file.
"""
# Define the local directory
cls._path = os.path.abspath(os.path.dirname(inspect.getfile(cls)))
# Create the markdown object
os.chdir(os.path.join(MooseDocs.MOOSE_DIR, 'docs'))
# Read the YAML configurations
config = MooseDocs.load_config(cls.CONFIG)
# Update extension list
if cls.EXTENSIONS:
for key in config:
if key not in cls.EXTENSIONS:
config.pop(key)
cls.updateExtensions(config)
cls.parser = MooseDocs.MooseMarkdown(extensions=config.keys(), extension_configs=config)
os.chdir(cls.WORKING_DIR)
def generate(config_file='moosedocs.yml',
generate=True,
locations=None,
**kwargs):
"""
Generates MOOSE system and object markdown files from the source code.
Args:
config_file[str]: (Default: 'moosedocs.yml') The MooseDocs project configuration file.
"""
# Read the configuration
config = MooseDocs.load_config(config_file)
_, ext_config = MooseDocs.get_markdown_extensions(config)
ext_config = ext_config['MooseDocs.extensions.MooseMarkdown']
# Run the executable
exe = MooseDocs.abspath(ext_config['executable'])
if not os.path.exists(exe):
raise IOError('The executable does not exist: {}'.format(exe))
else:
log.debug("Executing {} to extract syntax.".format(exe))
raw = mooseutils.runExe(exe, '--yaml')
yaml = mooseutils.MooseYaml(raw)
# Populate the syntax
for loc in ext_config['locations']:
for key, value in loc.iteritems():
if (locations == None) or (key in locations):
value['group'] = key
syntax = MooseDocs.MooseApplicationSyntax(
yaml,
generate=generate,
install=ext_config['install'],
**value)
log.info("Checking documentation for '{}'.".format(key))
syntax.check()
def latex(config_file=None, output=None, md_file=None, template=None, **template_args):
"""
Command for converting markdown file to latex.
"""
LOG.warning("The latex command is experimental and requires additional development to be "
"complete, please be patient as this develops.\nIf you would like to aid in "
"improving this feature please contact the MOOSE mailing list: "
"[email protected].")
# The markdown file is provided via the command line, thus it is provided relative to the
# current working directory. The internals of MooseDocs are setup to always work from the
# repository root directory (i.e., MooseDocs.ROOT_DIR), thus the path of this file must be
# converted to be relative to MooseDocs.ROOT_DIR.
md_file = os.path.relpath(os.path.abspath(md_file), MooseDocs.ROOT_DIR)
# Create the markdown parser
config = MooseDocs.load_config(config_file, template=template, template_args=template_args)
parser = MooseMarkdown(config)
# Build the html
builder = LatexBuilder(md_file=md_file, output=output, parser=parser)
builder.init()
builder.build(num_threads=1)
return 0
def setUpClass(cls):
"""
Create the markdown parser using the configuration file.
"""
# Define the local directory
cls._path = os.path.abspath(os.path.dirname(inspect.getfile(cls)))
# Create the markdown object
os.chdir(os.path.join(MooseDocs.MOOSE_DIR, 'docs'))
# Read the YAML configurations
config = MooseDocs.load_config(cls.CONFIG)
# Update extension list
if cls.EXTENSIONS:
for key in config:
if key not in cls.EXTENSIONS:
config.pop(key)
cls.updateExtensions(config)
cls.parser = MooseDocs.MooseMarkdown(extensions=config.keys(),
extension_configs=config)
os.chdir(cls.WORKING_DIR)
def setUpClass(cls):
config = MooseDocs.load_config(
os.path.join(MooseDocs.MOOSE_DIR, 'docs', 'website.yml'))
options = config['MooseDocs.extensions.app_syntax']
cls.database = MooseLinkDatabase(**options)
def setUpClass(cls):
config = MooseDocs.load_config(os.path.join(MooseDocs.MOOSE_DIR, 'docs', 'website.yml'))
options = config['MooseDocs.extensions.app_syntax']
cls.database = MooseLinkDatabase(**options)
def build(config_file=None, site_dir=None, num_threads=None, no_livereload=False, content=None,
dump=False, clean=False, serve=False, host=None, port=None, template=None, init=False,
**template_args):
"""
The main build command.
"""
if serve:
clean = True
site_dir = os.path.abspath(os.path.join(MooseDocs.TEMP_DIR, 'site'))
# Clean/create site directory
if clean and os.path.exists(site_dir):
LOG.info('Cleaning build directory: %s', site_dir)
shutil.rmtree(site_dir)
# Create the "temp" directory
if not os.path.exists(site_dir):
os.makedirs(site_dir)
# Check submodule for large_media
if MooseDocs.ROOT_DIR == MooseDocs.MOOSE_DIR:
status = submodule_status()
if status['docs/content/media/large_media'] == '-':
if init:
subprocess.call(['git', 'submodule', 'update', '--init',
'docs/content/media/large_media'], cwd=MooseDocs.MOOSE_DIR)
else:
LOG.warning("The 'large_media' submodule for storing images above 1MB is not "
"initialized, thus some images will not be visible within the "
"generated website. Run the build command with the --init flag to "
"initialize the submodule.")
# Check media files size
if MooseDocs.ROOT_DIR == MooseDocs.MOOSE_DIR:
media = os.path.join(MooseDocs.MOOSE_DIR, 'docs', 'content', 'media')
ignore = set()
for base, _, files in os.walk(os.path.join(media, 'large_media')):
for name in files:
ignore.add(os.path.join(base, name))
large = mooseutils.check_file_size(base=media, ignore=ignore)
if large:
msg = "Media files above the limit of 1 MB detected, these files should be stored in " \
"large media repository (docs/content/media/large_media):"
for name, size in large:
msg += '\n{}{} ({:.2f} MB)'.format(' '*4, name, size)
LOG.error(msg)
# Create the markdown parser
config = MooseDocs.load_config(config_file, template=template, template_args=template_args)
parser = MooseMarkdown(config)
# Create the builder object and build the pages
builder = WebsiteBuilder(parser=parser, site_dir=site_dir, content=content)
builder.init()
if dump:
print builder
return None
builder.build(num_threads=num_threads)
# Serve
if serve:
if not no_livereload:
server = livereload.Server(watcher=MooseDocsWatcher(builder, num_threads))
else:
server = livereload.Server()
server.serve(root=site_dir, host=host, port=port, restart_delay=0)
return 0
def build(config_file=None,
site_dir=None,
num_threads=None,
no_livereload=False,
clean=False,
serve=False,
host=None,
port=None,
**kwargs):
"""
The main build command.
"""
if serve:
clean = True
site_dir = os.path.abspath(os.path.join(MooseDocs.TEMP_DIR, 'site'))
# Clean/create site directory
if clean and os.path.exists(site_dir):
LOG.info('Cleaning build directory: %s', site_dir)
shutil.rmtree(site_dir)
# Create the "temp" directory
if not os.path.exists(site_dir):
os.makedirs(site_dir)
# Load the YAML configuration file
config = MooseDocs.load_config(config_file, **kwargs)
# Create the markdown parser
parser = MooseDocs.MooseMarkdown(extensions=config.keys(),
extension_configs=config)
# Create object for storing pages to be generated
def build_complete():
"""Builds complete documentation."""
builder = Builder(parser, site_dir)
builder.build(num_threads=num_threads)
return builder
builder = build_complete()
# Serve
if serve:
# Create the live server
server = livereload.Server()
# Watch markdown files
if not no_livereload:
for page in builder:
server.watch(page.source(), page.build)
# Watch support directories
server.watch(os.path.join(os.getcwd(), 'media'), builder.copyFiles)
server.watch(os.path.join(os.getcwd(), 'css'), builder.copyFiles)
server.watch(os.path.join(os.getcwd(), 'js'), builder.copyFiles)
server.watch(os.path.join(os.getcwd(), 'fonts'), builder.copyFiles)
# Watch the files and directories that require complete rebuild
server.watch(config_file, build_complete)
server.watch('templates', builder.build)
# Start the server
server.serve(root=site_dir, host=host, port=port, restart_delay=0)
return None
def build(config_file=None,
site_dir=None,
num_threads=None,
no_livereload=False,
content=None,
dump=False,
clean=False,
serve=False,
host=None,
port=None,
template=None,
init=False,
**template_args):
"""
The main build command.
"""
if serve:
clean = True
site_dir = os.path.abspath(os.path.join(MooseDocs.TEMP_DIR, 'site'))
# Clean/create site directory
if clean and os.path.exists(site_dir):
LOG.info('Cleaning build directory: %s', site_dir)
shutil.rmtree(site_dir)
# Create the "temp" directory
if not os.path.exists(site_dir):
os.makedirs(site_dir)
# Check submodule for large_media
if MooseDocs.ROOT_DIR == MooseDocs.MOOSE_DIR:
status = common.submodule_status()
if status['docs/content/media/large_media'] == '-':
if init:
subprocess.call([
'git', 'submodule', 'update', '--init',
'docs/content/media/large_media'
],
cwd=MooseDocs.MOOSE_DIR)
else:
LOG.warning(
"The 'large_media' submodule for storing images above 1MB is not "
"initialized, thus some images will not be visible within the "
"generated website. Run the build command with the --init flag to "
"initialize the submodule.")
# Check media files size
if MooseDocs.ROOT_DIR == MooseDocs.MOOSE_DIR:
media = os.path.join(MooseDocs.MOOSE_DIR, 'docs', 'content', 'media')
ignore = set()
for base, _, files in os.walk(os.path.join(media, 'large_media')):
for name in files:
ignore.add(os.path.join(base, name))
large = mooseutils.check_file_size(base=media, ignore=ignore)
if large:
msg = "Media files above the limit of 1 MB detected, these files should be stored in " \
"large media repository (docs/content/media/large_media):"
for name, size in large:
msg += '\n{}{} ({:.2f} MB)'.format(' ' * 4, name, size)
LOG.error(msg)
# Create the markdown parser
config = MooseDocs.load_config(config_file,
template=template,
template_args=template_args)
parser = MooseMarkdown(config)
# Create the builder object and build the pages
builder = WebsiteBuilder(parser=parser, site_dir=site_dir, content=content)
builder.init()
if dump:
print builder
return None
builder.build(num_threads=num_threads)
# Serve
if serve:
if not no_livereload:
server = livereload.Server(
watcher=MooseDocsWatcher(builder, num_threads))
else:
server = livereload.Server()
server.serve(root=site_dir, host=host, port=port, restart_delay=0)
return 0
