Skip to content

README.md

Latest commit

 

History

History
137 lines (90 loc) · 6.4 KB

README.md

File metadata and controls

137 lines (90 loc) · 6.4 KB

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 git@github.com: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!