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 andoverlay.
  2. Thecore directory stores the basic documentation that can be added as an external dependency (such as git submodule).
  3. Theoverlay 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 inoverlay, a file fromcore 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 incore oroverlay. 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 thecore andoverlay directories is only done when building the documentation, links from the articles inoverlay to the articles incore 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 theYFM-Docs utility.

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

To build the YDB OpenSource documentation, run the command:

  1. 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) assource_dir if the yfm command is called directly fromsource_dir. For example:

  1. 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:

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

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