1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
|
#
# 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
|