Python MooseDocs類代碼示例

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 generate_html(input, config_file):
  """
  Generates html from Moose flavored markdown.

  Args:
    input[str]: The *.md file to convert.
    config_file[str]: The *.yml configuration file.
  """
  # Load the config to extract MooseMarkdown settings
  #TODO: Make this more robust
  config = MooseDocs.yaml_load(config_file)
  md_config = config['markdown_extensions'][-1]['MooseDocs.extensions.MooseMarkdown']
  md_config['dot_ext'] = 'svg'

  # Convert markdown
  with open(input, 'r') as fid:
    md = fid.read()

  # Extract Jinja2 blocks
  settings = dict()
  def sub(match):
    settings[match.group(1).strip()] = eval(match.group(2))
    return ''
  md = re.sub(r'@\+\s*set\s+(.*?)=(.*?)\[email protected]', sub, md)

  moose = MooseDocs.extensions.MooseMarkdown(**md_config)
  parser = markdown.Markdown(extensions=[moose, 'markdown_include.include', 'admonition', 'mdx_math', 'toc', 'extra'])
  return parser.convert(md), settings

    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 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 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 __init__(self, **kwargs):
        super(AppSyntaxExtension, self).__init__(**kwargs)

        # Storage for the MooseLinkDatabase object
        self.syntax = None

        # Create the absolute path to the executable
        self.setConfig('executable', MooseDocs.abspath(self.getConfig('executable')))

 def _getSlideID(section):
     """
     Helper for getting slide name
     """
     match = re.search(r'#+\s*(.*?)\s*\n', section)
     if match:
         return MooseDocs.html_id(match.group(1))
     return None

    def _updateSyntax(self, path, objects, actions):
        """
        A helper for populating the syntax/filename/markdown databases. (private)

        Args:
          path[str]: A valid source directory to inspect.
        """
        reg_re = r'(?<!\:)register(?!RecoverableData|edError)\w+?\((?P<key>\w+)\);'
        reg_named_re = r'registerNamed\w+?\((?P<class>\w+),\s*"(?P<key>\w+)"\);'
        action_re = r'(registerActionSyntax|registerSyntax|registerSyntaxTask)\("(?P<action>\w+)"' \
                    r'\s*,\s*"(?P<key>.*?)\"[,\);]'

        # Walk the directory, looking for files with the supplied extension.
        for root, _, files in os.walk(MooseDocs.abspath(path), topdown=False):
            for filename in files:
                fullfile = os.path.join(root, filename)

                # Inspect source files
                if filename.endswith('.C') or filename.endswith('.h'):
                    fid = open(fullfile, 'r')
                    content = fid.read()
                    fid.close()

                    # Update class to source definition map
                    if filename.endswith('.h'):
                        for match in re.finditer(r'class\s*(?P<class>\w+)\b[^;]', content):
                            key = match.group('class')
                            self._filenames[key] = [fullfile]
                            src = fullfile.replace('/include/', '/src/')[:-2] + '.C'
                            if os.path.exists(src) and (src not in self._filenames[key]):
                                self._filenames[key].append(src)

                    # Map of registered objects
                    for match in re.finditer(reg_re, content):
                        key = match.group('key')
                        objects[key] = key

                    # Map of named registered objects
                    for match in re.finditer(reg_named_re, content):
                        name = match.group('class')
                        key = match.group('key')
                        objects[key] = name

                    # Action syntax map
                    for match in re.finditer(action_re, content):
                        key = match.group('key')
                        action = match.group('action')
                        actions[key].add(action)

        for root, _, files in os.walk(path, topdown=False):
            for filename in files:
                fullfile = os.path.join(root, filename)

                # Inspect source files
                name, ext = os.path.splitext(filename)
                if (ext == '.C') and (name in self._filenames):
                    self._filenames[name].append(fullfile)

    def __init__(self, markdown_instance=None, **kwargs):
        MooseMarkdownCommon.__init__(self, **kwargs)
        Preprocessor.__init__(self, markdown_instance)

        # Import the directly defined globals
        self._globals = kwargs.pop('globals', dict())

        # Add the defined globals from the supplied file(s)
        for filename in kwargs.pop('import'):
            self._globals.update(MooseDocs.yaml_load(os.path.join(MooseDocs.ROOT_DIR, filename)))

  def __init__(self, markdown_instance=None, **kwargs):
    MooseCommonExtension.__init__(self, **kwargs)
    Pattern.__init__(self, self.RE, markdown_instance)

    # Load the yaml data containing package information
    self.package = MooseDocs.yaml_load("packages.yml")

    # The default settings
    self._settings = {'arch' : None,
             'return' : None}

    def __init__(self, content=None, **kwargs):
        super(WebsiteBuilder, self).__init__(**kwargs)
        if (content is None) or (not os.path.isfile(content)):
            LOG.info("Using default content directory configuration "
                     "(i.e., --content does not include a valid filename).")
            content = dict(default=dict(base=os.path.join(os.getcwd(), 'content'),
                                        include=[os.path.join(os.getcwd(), 'content', '*')]))
        else:
            content = MooseDocs.yaml_load(content)

        self._content = content

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 setUpClass(cls):
        """
    Create the markdown parser using the 'moosedocs.yml' configuration file.
    """

        cwd = os.getcwd()
        os.chdir(os.path.join(MooseDocs.MOOSE_DIR, "docs"))

        config = MooseDocs.yaml_load("moosedocs.yml")

        extensions, extension_configs = MooseDocs.commands.get_markdown_extensions(config)
        cls.parser = markdown.Markdown(extensions=extensions, extension_configs=extension_configs)
        os.chdir(cwd)

def build(config_file='moosedocs.yml', live_server=False, pages='pages.yml', page_keys=[], clean_site_dir=False, **kwargs):
    """
    Build the documentation using mkdocs build command.

    Args:
        config_file[str]: (Default: 'mkdocs.yml') The configure file to pass to mkdocs.
    """
    pages = MooseDocs.load_pages(pages, keys=page_keys)
    config = mkdocs.config.load_config(config_file, pages=pages, **kwargs)
    update_extra()
    mkdocs.commands.build.build(config)
    mkdocs.utils.copy_media_files(config['docs_dir'], config['site_dir'])
    return config