Top.Mail.Ru
Documentation infrastructure | Tarantool
Tarantool
Check out the new release 2.8

Documentation infrastructure

This section of the documentation guidelines discusses some of the support activities that ensure the correct building of documentation.

The documentation source files are mainly stored in the documentation repository. However, in some cases, they are stored in the repositories of other Tarantool-related products or modules—Cartridge, Monitoring, and others.

If you are working with source files from a product or module repository, add that repository as a submodule to the documentation repository and configure other necessary settings. This will ensure that the entire body of Tarantool documentation, presented on the official website, is built properly.

Here is how to do that:

First, we need to add the repository with content source files as a submodule.

  1. Make sure you are in the root directory of the documentation repository.

  2. In the ./modules directory, add the new submodule:

    cd modules
    git submodule add https://<path_to_submodule_repository>
    cd ..
    
  3. Check that the new submodule is in the .gitmodules file, for example:

[submodule "modules/metrics"]
   path = modules/metrics
   url = https://github.com/tarantool/metrics.git

Now define what directories and files are to be copied from the submodule repository to the documentation repository before building documentation. These settings are defined in the build_submodules.sh file in the root directory of the documentation repository.

Here are some real submodule examples that show the logic of the settings.

The content source files for the metrics submodule are in the ./doc/monitoring directory of the submodule repository. In the final documentation view, the content should appear in the Monitoring chapter (https://www.tarantool.io/en/doc/latest/book/monitoring/).

To make this work:

  • Create a directory at ./doc/book/monitoring/.
  • Copy the entire content of the ./modules/metrics/doc/monitoring/ directory to ./doc/book/monitoring/.

Here are the corresponding lines in build_submodules.sh:

monitoring_root="${project_root}/modules/metrics/doc/monitoring" #
monitoring_dest="${project_root}/doc/book"

mkdir -p "${monitoring_dest}"
yes | cp -rf "${monitoring_root}" "${monitoring_dest}/"

The ${project_root} variable is defined earlier in the file as project_root=$(pwd). This is because the documentation build has to start from the documentation repository root directory.

The content source file for the cartridge_cli submodule is README.rst, located in the directory of the submodule repository. In the final documentation view, the content should appear here: https://www.tarantool.io/en/doc/latest/book/cartridge/cartridge_cli/.

To make this work:

  • Create a directory at ./doc/book/cartridge/cartridge_cli.
  • Copy ./modules/cartridge_cli/README.rst to ./doc/book/cartridge/cartridge_cli/index.rst.

Here ar the corresponding settings in build_submodules.sh:

rst_dest="${project_root}/doc/book/cartridge"
cartridge_cli_root="${project_root}/modules/cartridge-cli"
cartridge_cli_dest="${rst_dest}/cartridge_cli"
cartridge_cli_index_dest="${cartridge_cli_dest}/index.rst"

mkdir -p "${cartridge_cli_dest}"
yes | cp -rf "${cartridge_cli_root}/README.rst" "${cartridge_cli_index_dest}"

Finally, add paths to the copied directories and files to .gitignore.