Note

These are unedited stream-of-conciousness notes from reviewing SSGs and doc. generators.

Static site generators (SSGs)

Do they do everything in-house or use a framework?
How do you configure it? What can you configure?
How do you download, apply and use themes? How do you create new themes?

Static site generators

JuDoc.jl

Recent SSG written in Julia.
Implements its own Markdown parser it seems. Uses quite a lot of non-standard syntax.
Can serve the site via LiveServer.jl. Has live reload.
JS libraries are included by dropping them into the source directory and adding <link> tags manually.
Uses highlight.js for code highlighting.
Is able to pre-render KaTeX and highlighting, and to minify everything. Seems to call Node.js for that.
Has APIs to publish to GitHub. Pretty simple sequence of Git commands called with run.
Allows different page layouts via templates. Template is specified by a keyword argument.
The site can be built from pieces of HTML via templating.
Templates seem to be a collection of HTML parts and CSS files. Installation seems to be a matter of copying the files over.
Creation of new templates seems to just a matter of creating the new CSS and HTML files by hand.
Does not use any framework or anything (although any individual theme probably could).
It can also run Julia code and include the rendered output in the generated HTML.

Jekyll

Written in Ruby. Uses the jekyll program to run everything.
Site is configured with the _config.yml YAML file. Pages can also have front matter.
Jekyll appears to use the Liquid template language for its templates. It seems to be almost like a programming language allowing you to programmatically create content from data.
Themes appear to be a collection of HTML parts and SCSS files. Installation is a matter of copying over the files to the site source directory.
Use of frameworks etc. seems to be up to the theme.

Hugo

Written in Go. Run via the hugo binary.
Can serve locally, do live reload.
Themes appear to be just a set of CSS files,
Themes can also apparently be composed.
Frameworks etc. appear to be up to the theme.
Hugo appears to have its own templating language, but it seems similar to Liquid.
Has built-in support to process SASS/SCSS files.

MkDocs

Configures using the mkdocs.yml file. Use the mkdocs program to build etc.
Compiles Markdown pages into a static HTML site

Theming

Picking a theme is a matter of declaring it in the configuration file.
It comes with two built-in themes, but additional ones can be installed from PyPI.
Custom CSS and JS can be included with configuration options.
Uses a templating language for themes (Jinja2).
Each theme seems to have a mkdocs_theme.yml file which contains some configuration. Ok, apparently these are the options that the user can override.

Themes

The default theme uses Bootstrap, but frameworks and such are up to the theme.
The Material theme uses webpack to bundle assets etc. I.e. it appears to compile the theme into assets that can be served to the user. It seems that minified / SASSed / etc. theme files live in the repository too.
Material does "cache busting" for SVG images by adding a hash to the filename.

Other SSGs

E.g. Zola, Hyde are pretty similar to Jekyll or Hugo, just written in a different language.

Support theming and templates, but it's a matter of providing the files in the repo. Use of frameworks etc., is up to the theme.

Documentation generators

Sphinx

Used to generate Python docs. Historic note: Julia docs used to be built with Sphinx.

Uses reStructuredText, but can also do Markdown.
Supports multiple output formats
Configuration is done with a conf.py file, which can contain arbitrary Python code. It seems to work by declaring a bunch of global variables which act as the configuration keywords for Sphinx.

Styling and templating:

Does not seem to use any frameworks. Just a few custom CSS files.
Highlighting is done statically with Pygments.
Supports themes. Can be picked with a html_theme option.
Some of the themes can be further customized by setting html_theme_options dictionary.
Themes that are not built in can be installed as a Python package, or simply unpacked relative to the conf.py file. In the latter case you specify a set of paths where Sphinx will try to find the themes. You then pick the theme by its name as usual.
Themes themselves appear to be a set of .html and .css files written in a template language. Note that the templating language can be used to generate CSS files. There is also a theme.conf file that sets up a bunch of options — these can be customized with html_theme_options it seems.

Other interesting things to note:

It has the intersphinx extension to support cross-references between packages

JavaDoc

Default style is very spartan.
The docstring processing can apparently be extended with "doclets".
But doclets also allow the output to be changed completely it seems (e.g. PDFDoclet).

Doxygen

Configures with a Doxyfile
Math is either pre-rendered with latex to PNGs, or it can use MathJax.
Supports a lot of output formats (HTML, LaTeX, PDF, DocBook etc.)
Supports search via (1) JS based client-side search, (2) can deploy PHP scripts that perform search server-side, (3) can create a search a dataset that the user can load into their own indexer / search index. Uses the Solr XML index message format.
You can also generate XML output that you can then parse and generate the docs yourself. There is the Breathe tool which can convert the Doxygen XML to Sphinx RST input.

Controlling the HTML output

You can set hue, saturation and gamma values to determine the overall color scheme of the produced HTML output.
Some UI elements can also be disabled in the configuration (index, treeview)
HTML_DYNAMIC_SECTIONS will enable collapsed sections that the user has to click on
INTERACTIVE_SVG allows the user to generate interactive callgraphs that can be zoomed etc.
You can also override the page header, footer and CSS used
For the CSS, you can override the whole thing, but the recommended way is to provide an additional CSS stylesheet (to make it easier to upgrade)
The default style appears to be in-house.

rustdoc

docs.rs seems to use Pure.css
docs.rs constructs the site with the Handlebars template engine. Also has an SCSS style file. But this is probably for the landing page.
rustdoc seems to generate its own HTML, not unlike Documenter. Its style and JS files appear to be in-house.
docs.rs takes the rustdoc generated output, possibly parses and changes it a litte bit, but then just copies it over to the output directory it seems.
rustdoc does not seem to be able to do any theming or templating. There is a small widget to swap between light and dark themes though.

Conclusions & thoughts

How should we handle themes with DocumentationGenerator? Should we try to enforce a single theme? Or allow packages to use their own themes?
DocumentationGenerator would probably want to inject its own JS, CSS etc. at some point to all the docs. We should figure out a way to do that without having to edit the make.jl scripts.
I don't think Documenter should go full SSG and allow arbitrary templating (i.e. compile the site from HTML files with templating language). Although, an output format plugin that does that could definitely be an option (e.g. integrating with JuDoc).
It would also mean completely changing how the HTML site is generated. Right now it uses the DOM module to generate an HTML AST on the fly which then gets written out.
But maybe Documenter should allow some sort of customization of the generate HTML AST? An easy option is to add a lot of options (e.g. sidebar = false to completely remove the sidebar). But maybe, alternatively, the user could somehow override parts of the HTML generation programmatically?