scmRTOS Documentation Project

General

Two formats of scmRTOS documentation are available:

1. Static website for online access at https://scmrtos.github.io.
2. PDF manuals for offline use (downloadable from https://github.com/scmrtos/scmrtos-doc).

Both variants support two languages: English and Russian.

Building the Online Documentation

The online documentation is a static site generated by MkDocs with ReadTheDocs theme.

Two repositories are required to build and publish the site:

1. Sources (Markdown, MkDocs config, scripts, etc) - this repo.

2. The published site itself (https://github.com/scmrtos/scmrtos.github.io).

3. Ensure the repositories are arranged in the following directory layout:

├── ...
├── ...
├── project-site      <- current repo: sources
├── ...
└── scmrtos.github.io <- documentation site repo: target

2. Complete work in project-site. Push master branch to GitHub:

cd project-site
...
git push origin master

3. Switch to scmrtos.github.io. Activate the Python virtual environment:

source <path-to-venv>/bin/activate

4. Run this command:

mkdocs gh-deploy --config-file ../project-site/mkdocs.yml --remote-branch master

Generating PDF Manuals from MkDocs Markdown

1. To build the PDF documentation, run script/md2pdf.py. This script creates build directory and performs Markdown to PDF conversion for English and Russian documentation variants.

script/md2pdf.py

As a result, two PDFs will be placed at the project's root directory. The resulting project directory structure will look like this:

├── build             | build directory created by md->pdf conversion
├── docs              | sources
├── script            | scripts for md->pdf building
├── site              | project static site created by MkDocs
├── mkdocs.yml        | MkDocs config
├── README.md         | this file
├── scmrtos-en.pdf    | md->pdf result: English version of PDF documentation
└── scmrtos-ru.pdf    | md->pdf result: Russian version of PDF documentation

2. Move the generated scmrtos-en.pdf and scmrtos-ru.pdf files to the documentation storage repo (https://github.com/scmrtos/scmrtos-doc) replacing the old ones, then go to that repo and push the new PDF to GitHub:

git push origin master