298 lines
8.6 KiB
Python
298 lines
8.6 KiB
Python
#
|
|
# 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
|