cdoc2-system-docs

Intro

This is documentation for CDOC2 system, including analysis, protocol and format specification and architecture documentation.

Organisation of source files

Please follow these conventions:

• Approximately one chapter per one .md file. If needed, split larger files at section level. All files with .md extension will be automatically included. Also see mkdocs user guide.
• Use numbers in beginning of filenames for sorting .md files.
• Divide material under analysis/spec/architecture topics (subfolders docs/01_use_case_model, docs/02_protocol_and_cryptography_spec, docs/03_system_architecture). When needed, create additional topics.
• Put common acronyms and terms into docs/includes/abbreviations.md
• Put image files into the docs/img folder, so that they could be re-used from multiple .md files and refer to them with paths like ../img/SID_MID_full.png
• Follow Python-Markdown conventions and MkDocs Material features

Linting

markdownlint-cli2 "cdoc2-system-docs/**/*.md"

Local documentation generation tool-chain

It is possible to build the documentation using Python utilities mike and mkdocs. mike is used for creating persistent versions of the documentation which will not be changed once the documentation has changed. Those versions are created under a special gh-pages branch. Only use this locally, CI already uses mike, see GitLab instructions below.

1. Visual Studio Code (https://code.visualstudio.com)

2. Python with pip package manager

3. Install smaller Python packages and other requirements:

   pip3 install -r ../mkdocs_requirements.txt

4. Test the mkdocs utility

   mkdocs --version

5. Test the mike utility

   mike --version

6. Build a version of the documentation using mike, where 1.1 is an arbitrary version. Any other version name can be used. Then use mike serve to serve all built versions of the documentation under different URL-s.

   cd cdoc2-system-docs
   mike deploy 1.1
   mike serve

   If a default version number is not configured, then the documentation will be served at http://localhost:8000/v1/ , where v1 is the name of the version that was used with the deploy command.

7. Alternatively mkdocs can be used directly to build the documentation under the same git branch into the /site folder and served from there.

   cd cdoc2-system-docs
   mkdocs build
   mike serve

   The documentation should be served at http://127.0.0.1:8000/

Development process

1. Create RM ticket, if not already there, and corresponding GIT branch from master
2. Switch to new GIT branch in your working directory
3. Edit source code files with VSCode in docs/ folder, resolve linter errors, check with VSCode "Markdown: Open Preview" command
4. Run mkdocs serve and check the local website http://127.0.0.1:8000 within your browser
5. Commit and push to the branch
6. When the ticket is completed or feedback is needed, create GitLab MR (Merge Request)
7. After feedback and fixing problems, finish MR and merge changes to master branch
8. Check the published website https://cdoc2.pages.ext.cyber.ee/cdoc2-documentation/

Publish to GitHub Pages (open-eid.github.io/CDOC2)

1. Add open-eid remote (if not done already)

   git remote add github.com/open-eid [email protected]:open-eid/CDOC2.git
   git remote -v   

2. Add your SSH public key to your GitHub account (if not done already)

3. Publish to GitHub Pages

   mike deploy -F cdoc2-system-docs/mkdocs.yml --remote github.com/open-eid --deploy-prefix docs --branch gh-pages --push 1.1
   mike set-default -F cdoc2-system-docs/mkdocs.yml --remote github.com/open-eid --deploy-prefix docs --branch gh-pages --push 1.1

   where 1.1 is an arbitrary version

   Updated site is available at http://open-eid.github.io/CDOC2

   mike tool will generate mkdocs HTML site using mkdocs tool under directory docs and push it to gh-pages branch.

   Generated site files can be viewed https://github.com/open-eid/CDOC2/tree/gh-pages or by running git checkout gh-pages

   CDOC2 Pages configuration is configured to serve generated documentation from gh-pages branch and docs directory. More info from GitHub Pages

Publish to GitLab Pages (https://cdoc2.pages.ext.cyber.ee/cdoc2-documentation)

GitLab-CI handles publishing GitLab Pages.

To trigger the pipeline, a tag has to be added to the commit, and it has to start with letter v, for example v2.0.

Creating and changing tags

Tags are related to specific commits. It is important to know if tag already exists locally and in remote. Then, it should be removed from both first before adding it to a new commit.

To change a commit, remove it locally first: git tag -d <tagname>

Then remove it from remote using UI

To create the tag and add it to a commit, use the following command: git tag <tagname> <new-commit-hash>

If the desired commit is the last one, the commit hash can be skipped: git tag <tagname> e.g., git tag v2.0

Important! Tag names have to start with v, for example v2.0. They can be also longer and include additional data, e.g., v2.0.0-rc.0.

Finally, push the local tag to remote:

git push origin <tagname>

Change default version of documentation

When user navigates to the documentation URL, they are automatically redirected to a specific version of the docs.

Default version is managed by CI/CD variable DOC_DEFAULT_VERSION. To change the default version please change DOC_DEFAULT_VERSION variable before publishing a new tag under CI settings. It has to start with a number and not letter v, for example 2.0!