How to Author Documents
This site uses mkdocs to generate the documentation. The documentation is written in Markdown and uses MkDocs Material as the theme.
Setup¶
The documentation system requires the following tools to be installed:
- Python (3.11 or later)
- Poetry (2.1 or later)
- Docker, recommended is to use Docker Desktop in Mac. This is used to build the images for plantuml diagrams.
- Draw.io for creating diagrams other than plantuml This is not strictly required, but it is recommended to use it for creating diagrams in the documentation.
- Bibtex for managing references and citations. This is not strictly required, but it is recommended to use it for managing references and citations in the documentation.
- Pandoc for converting documents to different formats. This is not strictly required, but it is recommended to use it for converting documents to different formats.
- Latex for extended Math support. This is not strictly required, but it is recommended to use it for extended Math support in the documentation.
In addition to these tools, it is recommended to use VS Code as the editing environment with extensions for:
- Markdown Preview
- Markdown Lint
- Plantuml Preview
- Draw.io Integration
Markdown Formatting¶
PlantUml Diagrams¶
Mkdocs supports embedding PlantUml diagrams directly in the document text. See PlantUML Diagrams for details on how to use PlantUml.
Drawio Diagrams¶
Diagrams can also be created using Drawio.com using its ability to embed an editable diagram in an image file (in this case, PNG format files although SVG and other formats are also possible). To edit the diagrams, open the diagram image files in Drawio, either their desktop application, web version or their VSCode extension or IntelliJ plugin. The diagrams are stored in the assets subfolder of each section. Once you have edited the diagram, you can save it back to the same file and commit the changes to the repository.
BibTeX References¶
Mkdocs supports BibTeX to provide academic-style bibliography and citations.