src/tools/docwriter/siteconfig.py

#
#  siteconfig.py
#
#    Build site configuration and write to mkdocs.yml.
#
#  Copyright 2018 by
#  Nikhil Ramakrishnan.
#
#  This file is part of the FreeType project, and may only be used,
#  modified, and distributed under the terms of the FreeType project
#  license, LICENSE.TXT.  By continuing to use, modify, or distribute
#  this file you indicate that you have read the license and
#  understand and accept it fully.

"""Module to generate Mkdocs config.

This module contains routines to generate the configuration file
`mkdocs.yml` required by Mkdocs to build static HTML documentation
from markdown.

More information can be found at:

<https://www.mkdocs.org/user-guide/configuration/>
"""

from __future__ import print_function

import datetime
import logging

import yaml

import utils

log = logging.getLogger( __name__ )

# Config file name
config_filename = "mkdocs.yml"

# Docs directory and site directory
docs_dir = "markdown"
site_dir = "site"

# Basic site configuration default values
site_name        = "FreeType API Reference"
site_description = "API Reference documentation for FreeType"
site_author      = "FreeType Contributors"
use_dir_url      = False

# Theme configuration default values
theme_conf             = {}
theme_conf['name']     = "material"
theme_conf['logo']     = "images/favico.ico"
theme_conf['language'] = "en"
theme_conf['favicon']  = "images/favico.ico"
theme_conf['palette']  = {}
theme_conf['font']     = {}

# Theme palette
theme_conf['palette']['primary'] = "green"
theme_conf['palette']['accent']  = "green"

# Theme fonts
theme_conf['font']['text'] = "Noto Serif"
theme_conf['font']['code'] = "Roboto Mono"

# Markdown extensions
md_extensions = '''\
markdown_extensions:
  - toc:
      permalink: true
  - pymdownx.superfences:
      disable_indented_code_blocks: true
  - codehilite:
      guess_lang: false
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.magiclink
  - pymdownx.smartsymbols
'''

# Extra scripts
extra_scripts = '''\
extra_css:
  - 'stylesheets/extra.css'

extra_javascript:
  - 'javascripts/extra.js'
'''

# Other config
year     = datetime.datetime.utcnow().year
var_dict = { 'year': year }
other_config = '''\
copyright: Copyright {year} \
<a href = "https://www.freetype.org/license.html">\
The FreeType Project</a>.
'''
other_config = other_config.format( **var_dict )

def add_config( yml_string, config_name ):
    config = None
    try:
        config = yaml.safe_load( yml_string )
    except yaml.scanner.ScannerError:
        log.warn( "Malformed '%s' config, ignoring.", config_name )
    return config

def build_extras():
    # Parse all configurations and save as Python objects
    global md_extensions, yml_extra, yml_other
    md_extensions = add_config( md_extensions, "markdown_extensions" )
    yml_extra     = add_config( extra_scripts, "extra scripts" )
    yml_other     = add_config( other_config, "other" )


class  Chapter( object ):
    def __init__( self, title ):
        self.title = title
        self.pages = []

    def add_page( self, section_title, filename ):
        """Add a page to the chapter."""
        cur_page = {}
        cur_page[section_title] = filename
        self.pages.append( cur_page )

    def get_pages( self ):
        """Get dict of pages in the chapter."""
        conf = {}
        conf[self.title] = self.pages
        return conf


class  SiteConfig( object ):
    """Site configuration generator class.

    This class is used to generate site configuration based on supplied
    and default values.
    """
    def __init__( self ):
        self.site_config   = {}
        self.pages         = []
        self.chapter       = None
        self.sections      = []
        self.md_extensions = []

        # Set configurations
        self.site_name   = site_name
        self.site_desc   = site_description
        self.site_author = site_author
        self.docs_dir    = docs_dir
        self.site_dir    = site_dir
        self.theme_conf  = theme_conf
        self.use_dir_url = use_dir_url

    def set_site_info( self, name, description = None, author = None ):
        """Set the basic site information."""
        if name:
            self.site_name = name
        else:
            # Site name is required, throw warning and revert to default
            log.warn( "Site name not specified, reverting to default." )

        if description:
            self.site_desc = description
        if author:
            self.site_author = author

    def add_single_page( self, section_title, filename ):
        """Add a single page to the list of pages."""
        cur_page = {}
        cur_page[section_title] = filename
        self.pages.append( cur_page )

    def add_chapter_page( self, section_title, filename ):
        """Add a page to a chapter.

        Chapter must be set first using `start_chapter()` If not set,
        `add_single_page()` will be called internally.
        """
        if self.chapter:
            self.chapter.add_page( section_title, filename )
        else:
            log.warn( "Section '%s' added without starting chapter.",
                      section_title )
            self.add_single_page( section_title, filename )

    def start_chapter( self, chap ):
        """Start a chapter."""
        if self.chapter:
            self.end_chapter()

        self.chapter = Chapter( chap )

    def end_chapter( self ):
        """Explicitly end a chapter."""
        if self.chapter:
            chap_pages = self.chapter.get_pages()
            self.pages.append( chap_pages )
            self.chapter = None

    def build_site_config( self ):
        """Add basic Project information to config."""
        self.site_config['site_name'] = self.site_name
        if site_description:
            self.site_config['site_description'] = self.site_desc
        if site_author:
            self.site_config['site_author'] = self.site_author
        if docs_dir:
            self.site_config['docs_dir'] = self.docs_dir
        if site_dir:
            self.site_config['site_dir'] = self.site_dir
        if use_dir_url is not None:
            self.site_config['use_directory_urls'] = self.use_dir_url

    def build_theme_config( self ):
        # internal: build theme config
        if theme_conf != {}:
            self.site_config['theme'] = self.theme_conf

    def build_pages( self ):
        # internal: build pages config
        if self.pages != []:
            self.site_config['pages'] = self.pages

    def populate_config( self, data ):
        # internal: Add a given not None object to site_config
        if data:
            self.site_config.update( data )

    def write_config( self, name ):
        """Write all values in site_config to output stream."""
        if self.site_config != {}:
            print( "# " + name )
            print( yaml.dump( self.site_config, default_flow_style=False ) )
            self.site_config.clear()

    def write_config_order( self, name, order ):
        """Write all values in site_config to output stream in order."""
        if self.site_config != {}:
            print( "# " + name )
            for key in order:
                if key in self.site_config:
                    temp_config = {}
                    temp_config[key] = self.site_config[key]
                    print( yaml.dump( temp_config, default_flow_style=False ).rstrip() )
                    self.site_config.pop( key, None )

            if self.site_config != {}:
                # Print remaining values
                print( yaml.dump( self.site_config, default_flow_style=False ).rstrip() )

            # print an empty line
            print()
            self.site_config.clear()

    def build_config( self ):
        """Build the YAML configuration."""
        # End chapter if started
        self.end_chapter()

        # Open yml file
        output = utils.open_output( config_filename, config = True )

        # Build basic site info
        self.build_site_config()
        order = ['site_name', 'site_author', 'docs_dir', 'site_dir']
        self.write_config_order( "Project information", order )

        # Build theme configuration
        self.build_theme_config()
        self.write_config( "Configuration" )

        # Build pages
        self.build_pages()
        self.write_config( "Pages" )

        # Build extra scripts
        build_extras()

        # Add extra CSS and Javascript
        self.populate_config( yml_extra )
        self.write_config( "Customization" )

        # Add Markdown extensions
        self.populate_config( md_extensions )
        self.write_config( "Extensions" )

        # Add other options
        self.populate_config( yml_other )
        self.write_config( "Other Options" )

        # Close the file
        utils.close_output( output )

# eof