Here you find several examples of using Entangled with MkDocs.
This project is written using literate programming with Entangled. This means that some or all of its source code is contained in Markdown code blocks. These code blocks are kept synchronized with a compilable and debuggable version of the program. When you edit either the Markdown or the generated source files, make sure you have the Entangled daemon running:
entangled watchTe generate a rendered version of the Markdown, you may run
mkdocs buildor if you want to do both:
mkdocs serveEntangled will run inside the MkDocs event loop.
How to write code using Entangled
For didactic reasons we don’t always give the listing of an entire source file in one go. In stead, we use a system of references known as noweb (Ramsey 1994). You write code inside Markdown code blocks with the following syntax:
``` {.cpp title="src/main.cpp"}
#include <cstdlib>
#include <iostream>
<<main-function>>
```This creates a file src/main.cpp containing a not-yet-specified main function. This main function will print a friendly message on the screen.
``` {.cpp title="#hello-world"}
std::cout << "Hello, World!" << std::endl;
```To complete the program we need to create the main function.
``` {.cpp title="#main-function"}
int main(int argc, char **argv) {
<<hello-world>>
}
```Code blocks can be appended on with more code by repeating the same name for the code block.
``` {.cpp title="#hello-world"}
return EXIT_SUCCESS;
```The documentation is generated using MkDocs Material. See those pages for information on supported syntax and available plugins.
You may install the dependencies using poetry and activate the virtual environment before building:
poetry install
poetry shell
mkdocs build
If you don't (want to) use poetry:
python -m venv venv
./venv/bin/activate
pip install .
mkdocs build
This template is licensed under the Apache License v2.0. See LICENSE.