Documentation

The documentation is written in markdown and is built using mdbook.

See documentation tools for more information on how to install and usemdbook.

The documentation is located in the docs directory and is split in two parts: taxonomy and development.

This is the docs/development part of the documentation and it is intended for developers working on the JobTech Taxonomy API. It explains how the system is built, how to set up a development environment, how to build and run the system, how to test it, and how to deploy it.

The docs/taxonomy part is the user documentation and is intended for users of the JobTech Taxonomy API. It explains what the Taxonomy is, what information it contains, how to use it, and how to integrate it with other systems.

Writing the documentation

Linting

When writing the documentation, do use the markdown linter and the spell checker.

The documentation is written in markdown and require no special tools to edit. You can use any text editor to write the documentation. To see the changes as you write you can however use mdbook to serve the documentation locally.

Serving the documentation

To serve the documentation locally run:

mdbook serve docs/taxonomy

or, if you wish to run mdbook in a way that allows you to access the documentation from other devices on your network:

mdbook serve -n 0.0.0.0 docs/taxonomy

Substitute docs/taxonomy for docs/development if you wish to work on the development part of the documentation.

Building the documentation

The CI system will build both the development and taxonomy parts of the documentation. It will then publish the development part to the GitLab Pages for the JobTech Taxonomy API repository. The taxonomy part is embedded into the image built for deployment of the JobTech Taxonomy API.

To build the documentation locally run:

mdbook build docs/taxonomy

or, if you wish to build the development part of the documentation:

mdbook build docs/development

Tools

Both mdbook and the plugins listed below are included in the CI Tools image. The plugins are used to render diagrams, admonition boxes, and provide tools to be used in the documentation. They are not required to build the documentation but are useful to make it more readable and informative.

Plugins

The following plugins are used to render diagrams, admonition boxes, and provide tools to be used in the documentation:

mdbook-admonish

This plugin allows you to add fancy notes to your documentation.

    ```admonish warning
    Writing software without tests is like skydiving without a parachute.
    ```

Will display as:

Warning

Writing software without tests is like skydiving without a parachute.

mdbook-katex

This lets us write math in the LaTeX style.

$$ \eta \beta \pi $$ becomes $$ \eta \beta \pi $$

mdbook-plantuml
    ```puml
    @startuml Hello!
    Bob->Alice : Hello!
    @enduml
    ```

Will display as:

PlantUML rendering error: Failed to generate diagram (error sending request for url (https://www.plantuml.com/plantuml/svg/SoWkIImgAStDKV18pSd9L-Hooa_IjNFCoKnELR22YJcavgK0bN0100==): error trying to connect: error:0A000086:SSL routines:tls_post_process_server_certificate:certificate verify failed:../ssl/statem/statem_clnt.c:1889: (unable to get local issuer certificate))

mdbook-mermaid
    ```mermaid
    mindmap
      root((Mermaid))
        Can be used for graphs
          Graphs
          Diagrams
          Flowcharts
        Just
          Another
            Tool
            Brick
          This
    ```

Will display as:

mindmap
  root((Mermaid))
    Can be used for graphs
      Graphs
      Diagrams
      Flowcharts
    Just
      Another
        Tool
        Brick
      This