Any version of the documentation is built using a common template:
- The basic build directory contains two directories:
coredirectory stores the basic documentation that can be added as an external dependency (such as git submodule).
overlaydirectory stores content that is specific for this build.
- The contents of the core directory are copied to the working directory.
- 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
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.
Since the overlay of the
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
source_diris the directory where the contents of https://github.com/ydb-platform/ydb/tree/main/ydb/docs is cloned.
output_diris the output directory for HTML files.
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: