This is a first MkDocs setup using the material theme. It is living only in this repo and is not yet configured in ReadTheDocs.
As a basis I used the MkDocs setup provided in #1659 by Kosta Vukicevic (stcksmsh). I minimized it as much as possible, investigated the plugins/extensions and tried to document them in the mkdocs.yml config file with comments.
The content of the manual is not modified. It is nearly the same as the current one generated by our Sphinx setup.
I reduce the file size of the screenshot images by ~13% using optipng.
I created the folder /doc/manual in the repo for BIT's user manual. In the future I would create the code reference docu in something like /doc/reference or /doc/coderef.
Next task in follow-up PRs are:
Document the build dependencies to generate the doc.
Update our doc-dev documents regarding MkDocs.
Add user-callback docu (Kosta will do this in #1659)
Setup ReadTheDocs to use this MkDocs.
To generate the doc on your local system, navigate into /doc/manual. Now you have to options: 1) Run mkdocs build to generate HTML and open /doc/manual/html/index.html, or 2) run mkdocs serve and start your browser with http://127.0.0.1:8000 ("localhost:8000" doesn't work on my system). You can modify the config and the content (md-files) life while the server runs.
This is a first MkDocs setup using the material theme. It is living only in this repo and is not yet configured in ReadTheDocs.
As a basis I used the MkDocs setup provided in #1659 by Kosta Vukicevic (stcksmsh). I minimized it as much as possible, investigated the plugins/extensions and tried to document them in the mkdocs.yml config file with comments.
The content of the manual is not modified. It is nearly the same as the current one generated by our Sphinx setup. I reduce the file size of the screenshot images by ~13% using
optipng.I created the folder
/doc/manualin the repo for BIT's user manual. In the future I would create the code reference docu in something like/doc/referenceor/doc/coderef.Next task in follow-up PRs are:
To generate the doc on your local system, navigate into
/doc/manual. Now you have to options: 1) Runmkdocs buildto generate HTML and open/doc/manual/html/index.html, or 2) runmkdocs serveand start your browser with http://127.0.0.1:8000 ("localhost:8000" doesn't work on my system). You can modify the config and the content (md-files) life while the server runs.Did I forget something?
❤️ I love it as much as I work with it. ❤️