diff options
Diffstat (limited to 'src/tools/docwriter/siteconfig.py')
| -rw-r--r-- | src/tools/docwriter/siteconfig.py | 297 |
1 files changed, 0 insertions, 297 deletions
diff --git a/src/tools/docwriter/siteconfig.py b/src/tools/docwriter/siteconfig.py deleted file mode 100644 index 347f35201..000000000 --- a/src/tools/docwriter/siteconfig.py +++ /dev/null @@ -1,297 +0,0 @@ -# -# 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 |