Documentation
Getting started
This documentation is done using MkDocs with multiple plugins enabled. It's based on the Markdown, you can find basic syntax overview here.
In order to contribute to the documentation, you'll need to have Git and Docker installed on your machine as well as any editor of your choice, preferably supporting Markdown preview. You can run the preview server using following command:
Now you can open continuously updated preview of your edits in browser at http://127.0.0.1:8000. Pages will be automatically updated while you're editing.
Additionally you can run
to make sure that your changes will be built correctly and doesn't break documentation.
Workflow
If you want to quick edit any page in the documentation, you can press the Edit this page
icon at the top right of the page. It'll open the page in the GitHub editor. You can edit it and create a pull request with your changes.
Please, never push to the master
or release/*
branches directly. Always create a pull request and wait for the review.
Each pull request will be automatically built and preview will be deployed. You can find the link to the preview in the comments in pull request.
Repository
Documentation is organized in per-release branches:
master
- ongoing development, not released yet, referenced asdev
version in the documentationrelease/alpha-1
/release/alpha-2
- alpha releases, referenced asalpha-1
/alpha-2
versions in the documentation, if patches released for alpha-1, they'll be merged intorelease/alpha-1
branchrelease/v1.0
- first stable release, referenced asv1.0
version in the documentation, if patches (e.g.v1.0.1
) released for v1.0, they'll be merged intorelease/v1.0
branch
Latest release branch is referenced as latest
version in the documentation and will be used by default when you open the documentation.
File layout
All documentation files are located in docs
directory. Each file is a Markdown file with .md
extension. You can create subdirectories to organize your files. Each directory can have a .pages
file that overrides the default navigation order and titles.
For example, top-level .pages
in this repository looks like this:
nav:
- index.md
- getting-started
- concepts
- Wiring Diagram: wiring
- Install & Upgrade: install-upgrade
- User Guide: user-guide
- Reference: reference
- Troubleshooting: troubleshooting
- ...
- release-notes
- contribute
Where you can add pages by file name like index.md
and page title will be taked from the file (first line with #
). Additionally, you can reference the whole directory to created nested section in navigation. You can also add custom titles by using :
separator like Wiring Diagram: wiring
where Wiring Diagram
is a title and wiring
is a file/directory name.
More details in the MkDocs Pages plugin.
Abbreviations
You can find abbreviations in includes/abbreviations.md
file. You can add various abbreviations there and all usages of the defined words in the documentation will get a highlight.
For example, we have following in includes/abbreviations.md
:
It'll highlight all usages of HHFab
in the documentation and show a tooltip with the definition like this: HHFab.
Markdown extensions
We're using MkDocs Material theme with multiple extensions enabled. You can find detailed reference here, but here you can find some of the most useful ones.
To view code for examples, please, check the source code of this page.
Text formatting
Text can be deleted and replacement text added. This can also be
combined into onea single operation. Highlighting is also
possible and comments can be added inline.
Formatting can also be applied to blocks by putting the opening and closing tags on separate lines and adding new lines between the tags and the content.
Keyboard keys can be written like so:
Ctrl+Alt+Del
Amd inline icons/emojis can be added like this:
Admonitions
Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow. Different types of admonitions are available, each with a unique icon and color. Details can be found here.
Lorem ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
Code blocks
Details can be found here.
Simple code block with line nums and highlighted lines:
bubble_sort.py | |
---|---|
Code annotations:
- I'm a code annotation! I can contain
code
, formatted text, images, ... basically anything that can be written in Markdown.
Tabs
You can use Tabs to better organize content.
Tables
Method | Description |
---|---|
GET |
Fetch resource |
PUT |
Update resource |
DELETE |
Delete resource |
Diagrams
You can directly include Mermaid diagrams in your Markdown files. Details can be found here.
graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
sequenceDiagram
autonumber
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!