Package: aep-site-generator
aep.dev static site generatorThis is the site generator foraep.devand its forks. It
takes AEP files in a git repository and outputs a static website.Why?We are not fans of rolling our own tools when off-the-shelf alternatives exist.
However, the AEP project has grown sufficiently mature to warrant it.GitHub Pages normally automatically builds documentation withJekyll, but
as the AEP system has grown, we are beginning to reach the limits of what
Jekyll can handle, and other off-the-shelf generators had similar issues:AEP adoption is handled through fork-and-merge and top-down configuration
files will lead to repetitive merge conflicts.Our grouping and listing logic has grown complicated, and had to be
maintained using complex and error-prone Liquid templates.Jekyll is extensible but GitHub requires specific Jekyll plugins, meaning we
can not use off-the-shelf solutions for planned features (e.g. tabbed code
examples).Lack of meaningful build CI caused failures.Working with the development environment was (really) slow.There are some additional advantages that we unlock with a custom generator:We can override segments of AEPs using template extensions in new files
rather than modifying existing files.We can provide useful abstractions for common deviations between companies
(e.g. case systems) that minimize the need to fork AEPs.We can customize the Markdown parsing where necessary (tabs, hotlinking,
etc.).How does it work?This is essentially split into three parts:Python code (aep_site/):The majority of the code is models (aep_site/models/) that represent the
fundamental concept of an AEP site. These are rolled up into a singleton
object calledSitethat is used everywhere. All models aredataclassesthat get sent to templates.There is also a publisher class (aep_site/publisher.py) that is able to
slurp up a repo of AEPs and build a static site.There is some server code (aep_site/server.py) that can run a development
server.All remaining files are thin support code to avoid repeating things in or
between the above.Templates (support/templates/) areJinja2templates containing (mostly)
HTML that makes up the layout of the site.Assets (support/assets/andsupport/scss/) are other static files. SCSS
is automatically compiled into CSS at publication.Of the models, there are three models in particular that matter:Site:A singleton that provides access to all scopes, AEPs, and static
pages. This is sent to every template as thesitevariable.AEP:A representation of a single AEP, including both content and
metadata. This is sent to the AEP rendering template as theaepvariable.Scope:A group of AEPs that apply to a particular scope. The "general"
scope is special, and is the "root" group. This is sent to the AEPlistingtemplate as thescopevariable.Templates arejinja2files in thetemplates/directory.Note:We run Jinja in with "strict undefined", so referencing an undefined
variable in a template is a hard error rather than an empty string.Entry pointsThere are two entry points for the app. Thepublisher(aep_site/publisher.py) is the program that iterates over the relevant
directories, renders HTML files, and writes them out to disk. Theapp(aep_site/server.py) is a lightweight Flask app that provides a development
server.These entry points are routed through the CLI file (aep_site/cli.py); when
this application is installed using pip, it makes theaep-site-gen(publisher) andaep-site-serve(server) commands available.ExtensionsThis site generator includes a basic extension system for AEPs. When processing
AEPs as plain Markdown files, it will make any Markdown (level 2 or 3) header
into a block. Therefore...## Foo bar bazLorem ipsum dolor set ametBecomes...{% block foo_bar_baz %}
## Foo bar baz

Lorem ipsum dolor set amet
{% endblock %}That allows an overriding template to extend the original one and override
sections:{% extends aep.templates.generic %}

{% block foo_bar_baz %}

## My mo-betta foo bar baz

Lorem ipsum dolor set something-not-amet
{% endblock %}Developer SetupIf you want to contribute to this project you will want to have a setup where
you can make changes to the code and see the result of your changes as soon as
possible. Here is a quick way to set up a local development environment that
will enable you to work on the code without having to reinstall the command
line scripts.DependenciesYou'll need venv. On Linux, install with,sudo apt-get install python3-venvRunning dev envCheck out the source$mkdirsrc
$cdsrc
$gitclonehttps://github.com/aep-dev/site-generator.gitSetup python virtual environment$python3-mvenv.venv
$source.venv/bin/activatePIP Install with the editable option$pipinstall--editable.Serve the aep.dev site$aep-site-serve/path/to/aep/data/on/your/systemUsing the docker containerFor quick serving, a docker container can also be used, wrapped in
a convenience scriptserve.sh../serve.sh