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:
1. Add a submodule
First, we need to add the repository with content source files as
a submodule.
Make sure you are in the root directory of the documentation repository.
In the ./modules
directory, add the new submodule:
cd modules
git submodule add https://<path_to_submodule_repository>
cd ..
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
2. Update build_submodules.sh
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}"
First, we need to add the repository with content source files as a submodule.
Make sure you are in the root directory of the documentation repository.
In the
./modules
directory, add the new submodule:cd modules git submodule add https://<path_to_submodule_repository> cd ..
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
2. Update build_submodules.sh
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}"
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}"