00-index.Rmd

---
title: "Writing autogenerated documents with lightweight markup languages (LMLs)"
description: |
  A detailed analysis of existing tools for automatically generating documents from markup sources
author:
  - name: Unai Martinez-Corral
    url: https://github.com/umarcor
    affiliation: "Digital Electronics Design Group, University of the Basque Country (UPV/EHU)"
    affiliation_url: https://ehu.eus/gded
date: "`r Sys.Date()`"
#date: 'Last updated on [`r system("git log -1 --format=%at | xargs -I{} date -d @{} +%Y/%m/%d", intern=TRUE)`](https://github.com/umarcor/ghdl-cosim/commit/`r system("git rev-parse HEAD", intern=TRUE)`) and generated on `r format(Sys.time(), "%Y/%m/%d")`'
bibliography: refs.bib
output:
  distill::distill_article:
    toc: true
    toc_depth: 5
repository_url: https://github.com/dbhi/docascode
citation_url: https://dbhi.github.io/docascode
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE)
```

**THIS DOCUMENT IS WORK IN PROGRESS.**
**IT IS A COMPENDIUM OF REFERENCES AND THOUGHTS OF THE AUTHOR GIVEN THE ASIMETRIC EXPERIENCE WITH THE DIFFERENT TOOLS.**
**HENCE, USING IT FOR COMPARISON OF TOOLS IS CURRENTLY UNFAIR.**
**PLEASE, TAKE IT WITH A GRAIN OF SALT.**

Engineers, software developers and hardware designers need to write documentation.
It might be arguable whether they need to write the docs in their final layout, or some other colleague will take care
of enhancing them.
Nonetheless, it is undoubtable that only the authors of some project can properly describe the complex features,
implementations and motivations.
As a result, tens of tools have been proposed to ease the transition from notes/comments written by developers to proper
references, tutorials, how-tos, etc.
Typically, the workflow starts with writing the docs in some plain text format with some specific markup or decorations.
The text is either written in the sources (in software/hardware designs) or anyway distributed using the same workflow
as for the codebase.
Then, *documentation generator* tools are used to extract the content and convert/manipulate it to some other
(typically prettier) format.
The chain might include multiple conversions to multiple output formats (say HTML, LaTeX, PDF, EPUB, man pages, etc.).

<aside>
<a
  title="'dbhi/docascode' GitHub repository"
  href="https://github.com/dbhi/docascode"
><img
  src="https://img.shields.io/github/stars/dbhi/docascode?longCache=true&style=flat-square&label=dbhi%2Fdocascode&logo=github&color=b9b8b7"
  data-external="1"
></a><!--
-->
<a
  title="'Build' workflow Status"
  href="https://github.com/dbhi/docascode/actions/workflows/Build.yml"
><img
  alt="'Build' workflow Status"
  src="https://img.shields.io/github/actions/workflow/status/dbhi/docascode/Build.yml?branch=main&longCache=true&style=flat-square&logo=github&label=Build"
  data-external="1"
></a>
</aside>

In this document it is assumed that the reader is aware of what has been described so far.
It is not the purpose of the author to convince the reader about why writing documents using markup languages and source
code management (SCM) pays off [@kdheepak15] [@sablonniere17] [@xie17] [@almiray19].
Neither it is to write an introduction to *documentation as code* (Docs-as-Code) or to *documentation generators*.
By the same token, how to organize the content and/or which kind of documentation to generate is better discussed in
many other references.
For instance, [@divio-documentation] [@procida17] is a very interesting approach to organizing docs into *Tutorials*,
*How-tos*, *Discussions* and *References*.
*Write the Docs* "*is a global community of people who care about documentation*", where learning resources are provided
and conferences are organized [@writethedocs].

<aside>
**W** [Comparison of documentation generators](https://en.wikipedia.org/wiki/Comparison_of_documentation_generators),
[Lightweight markup language](https://en.wikipedia.org/wiki/Lightweight_markup_language),
[Version control](https://en.wikipedia.org/wiki/Version_control)
</aside>

Overall, there are lots of articles about how certain users/groups/projects use some specific tool to generate some
specific output format, typically involving non negligible custom (thus, specific) glue logic.
Yet, all of them are likely to be feature-limited, mostly because building robust documentation tools does not pay off.
It is typically a side project; people need it to have their target achieved, but the documentation system is not a
target by itself.
It is not until one needs to actually use one of these tools that limitations and unsupported features start to arise.
It's software, and everything can be potentially done.
But there is frequently a large gap between *"can be done"* and *"it is currently possible to do it"*.

This document is an analysis of multiple *documentation generators* or *site generators*, focused on telling what is
currently possible, easy or difficult to achieve.