Building documentation

Build technology

Overlaying layers

Any version of the documentation is built using a common template:

  1. The basic build directory contains two directories: core and overlay.
  2. The core directory stores the basic documentation that can be added as an external dependency (such as git submodule).
  3. The overlay directory stores content that is specific for this build.
  4. The contents of the core directory are copied to the working directory.
  5. The contents of the overlay directory are copied to the working directory, replacing any file whose relative path in the overlay directory matches that of any file from the core directory.

As a result, the working directory of the build contains the content from the core directory, in which the files present in the overlay directory are replaced. If a certain file is missing in overlay, a file from core gets to the build.

This overlay allows redefining the content, preserving the placement of articles, that is, keeping any links to them from other articles, whether they come from articles placed in core or overlay. As a result, content adaptation can be carried out within the article that requires adaptation, without the need to make technical adjustments in other articles.

Warning

Since the overlay of the core and overlay directories is only done when building the documentation, links from the articles in overlay to the articles in core won't be clickable in an integrated development environment (IDE) that knows nothing about the fact that some directories will be overlaid on top of each other during the build.

Local build with OpenSource tools

The documentation is built using the YFM-Docs utility.

The procedure for installing YFM-Docs is described on introductory documentation page for this utility.

To build the YDB OpenSource documentation, run the command:

yfm -i <source_dir> -o <output_dir> --allowHTML

Where:

Building the documentation takes a few seconds and there should be no errors logged to the stdout.

You can specify . (a dot) as source_dir if the yfm command is called directly from source_dir. For example:

yfm -i . -o ~/docs/ydboss --allowHTML

To view the documentation built locally, you can open the directory from your browser or use a simple web server built into Python:

python3 -m http.server 8888 -d ~/docs/ydboss

With the server run in this way, the locally built documentation is available at the links: