From e03be34475ea7929f9121fa579624e2ce6be63e9 Mon Sep 17 00:00:00 2001 From: Evgeniy Osintsev Date: Thu, 11 Feb 2021 10:54:29 +0300 Subject: [PATCH 1/2] Add a new section in the Documentation guidlines related to documentation infrastructure with the description of adding a submodule into the documentation repository. Closes #1763 --- doc/contributing/docs.rst | 3 +- doc/contributing/docs/doc_infrastructure.rst | 136 +++++++++++++++++++ 2 files changed, 138 insertions(+), 1 deletion(-) create mode 100644 doc/contributing/docs/doc_infrastructure.rst diff --git a/doc/contributing/docs.rst b/doc/contributing/docs.rst index 9daedd47b5..91f110afda 100644 --- a/doc/contributing/docs.rst +++ b/doc/contributing/docs.rst @@ -15,4 +15,5 @@ The guidelines are a work in progress, and we welcome all contributions. docs/markup docs/style - docs/examples \ No newline at end of file + docs/examples + docs/doc_infrastructure diff --git a/doc/contributing/docs/doc_infrastructure.rst b/doc/contributing/docs/doc_infrastructure.rst new file mode 100644 index 0000000000..0393bb5be3 --- /dev/null +++ b/doc/contributing/docs/doc_infrastructure.rst @@ -0,0 +1,136 @@ + +Documentation infrastructure +============================= + +In this section of the :doc:`documentation guidelines `, +we deal with some support activities to ensure the correct building of +documentation. + +.. _guidelines_doc_submodules: + +Documentation submodules +--------------------------- + +The source files with the documentation content are mainly stored in the +`documentation repository `_. +However, in some of the cases the content source files are stored in +repositories of other Tarantool-related products and modules, for example, +`Cartridge `_, +`Monitoring `_, +and some others. + +In this case, we need to add such a repository containing the source files +as a submodule to the `documentation repository `_ +and set up other necessary settings to ensure the proper building of the entire +body of Tarantool documentation presented at the `official web-site `_. + +The steps to do that is the following: + +.. contents:: + :local: + :depth: 1 + +.. _guidelines_doc_submodules_add: + +Adding a submodule +~~~~~~~~~~~~~~~~~~~ + +First, we need to add a repository containing the content source files as +a submodule. + +#. Make sure you are in the root directory of the documentation repository. + +#. Update the ``.gitmodules`` file by adding a new ``[submodule ...]`` section, + for example: + + .. code-block:: bash + + [submodule "modules/metrics"] + path = modules/metrics + url = https://github.com/tarantool/metrics.git + +#. In the ``/modules`` directory, add the new submodule: + + .. code-block:: bash + + cd modules + git submodule add https:// + cd .. + +.. _guidelines_doc_submodules_update: + +Updating ``update_submodule.sh`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Next, we should define what directories and files are to be copied from +the submodule repository into the documentation one before building +documentation. These settings are defined in the ``update_submodule.sh`` file +which is in the root directory of the documentation repository. + +We can take examples of the already existing submodules to show the logic of +the settings. + +``metrics`` +^^^^^^^^^^^^ + +In case of the ``metrics`` submodule, the content source files 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/``). + +So, we need to: + +* in ``/doc/book``of the documentation repository, create + the ``/monitoring`` sub-directory +* copy the entire content of the ``/doc/monitoring`` directory of the submodule + repository to the ``/doc/book/monitoring`` of the documentation repository. + +The corresponding settings in the ``update_submodule.sh`` file are the following: + +.. code-block:: bash + + 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 as ``project_root=$(pwd)``. +We should start the documentation build from the documentation repository root +directory so that will be the value of the variable. + +``cartridge_cli`` +^^^^^^^^^^^^^^^^^^ + +In case of the ``cartridge_cli`` submodule, the content source is in +the ``README.rst`` file 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/``. + +So, we need to: + +* in ``/doc/book/cartridge``of the documentation repository, create + the ``/cartridge_cli`` sub-directory +* copy the ``README.rst`` file from the submodule + repository to the ``/doc/book/cartridge/cartridge_cli`` directory of the + documentation repository and rename it to ``index.rst``. + +The corresponding settings in the ``update_submodule.sh`` file are the following: + +.. code-block:: bash + + 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}" + +.. _guidelines_doc_submodules_gitignore: + +Updating ``.gitignore`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Finaly, we should add paths to the copied directories and files to +the ``.gitignore`` file. From ed4f01675d9f6b79b303eaa97265fd8b9777bea5 Mon Sep 17 00:00:00 2001 From: Nick Volynkin Date: Fri, 12 Feb 2021 20:33:07 +0700 Subject: [PATCH 2/2] Use shorter page name, add minor improvements --- doc/contributing/docs.rst | 2 +- .../{doc_infrastructure.rst => infra.rst} | 86 +++++++++---------- 2 files changed, 43 insertions(+), 45 deletions(-) rename doc/contributing/docs/{doc_infrastructure.rst => infra.rst} (55%) diff --git a/doc/contributing/docs.rst b/doc/contributing/docs.rst index 91f110afda..f3e87f661e 100644 --- a/doc/contributing/docs.rst +++ b/doc/contributing/docs.rst @@ -16,4 +16,4 @@ The guidelines are a work in progress, and we welcome all contributions. docs/markup docs/style docs/examples - docs/doc_infrastructure + docs/infra diff --git a/doc/contributing/docs/doc_infrastructure.rst b/doc/contributing/docs/infra.rst similarity index 55% rename from doc/contributing/docs/doc_infrastructure.rst rename to doc/contributing/docs/infra.rst index 0393bb5be3..1254499b88 100644 --- a/doc/contributing/docs/doc_infrastructure.rst +++ b/doc/contributing/docs/infra.rst @@ -8,8 +8,8 @@ documentation. .. _guidelines_doc_submodules: -Documentation submodules ---------------------------- +Adding submodules +----------------- The source files with the documentation content are mainly stored in the `documentation repository `_. @@ -24,7 +24,7 @@ as a submodule to the `documentation repository `_. -The steps to do that is the following: +The steps to do that are the following: .. contents:: :local: @@ -32,34 +32,34 @@ The steps to do that is the following: .. _guidelines_doc_submodules_add: -Adding a submodule -~~~~~~~~~~~~~~~~~~~ +1. Add a submodule +~~~~~~~~~~~~~~~~~~ First, we need to add a repository containing the content source files as a submodule. -#. Make sure you are in the root directory of the documentation repository. +#. Make sure you are in the root directory of the documentation repository. -#. Update the ``.gitmodules`` file by adding a new ``[submodule ...]`` section, - for example: +#. In the ``./modules`` directory, add the new submodule: - .. code-block:: bash + .. code-block:: bash - [submodule "modules/metrics"] - path = modules/metrics - url = https://github.com/tarantool/metrics.git + cd modules + git submodule add https:// + cd .. -#. In the ``/modules`` directory, add the new submodule: - .. code-block:: bash +#. Check that the new submodule appears in the ``.gitmodules`` file, for example: - cd modules - git submodule add https:// - cd .. + .. code-block:: ini + + [submodule "modules/metrics"] + path = modules/metrics + url = https://github.com/tarantool/metrics.git .. _guidelines_doc_submodules_update: -Updating ``update_submodule.sh`` +2. Update ``update_submodule.sh`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Next, we should define what directories and files are to be copied from @@ -74,26 +74,26 @@ the settings. ^^^^^^^^^^^^ In case of the ``metrics`` submodule, the content source files are in the -``/doc/monitoring`` directory of the submodule repository. In the final -documentation view, the content should appear in the `Monitoring `_ +``/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/``). So, we need to: -* in ``/doc/book``of the documentation repository, create - the ``/monitoring`` sub-directory -* copy the entire content of the ``/doc/monitoring`` directory of the submodule - repository to the ``/doc/book/monitoring`` of the documentation repository. +* create a directory at ``./doc/book/monitoring/``. +* copy the entire content of the ``./modules/metrics/doc/monitoring/`` directory to + ``./doc/book/monitoring/``. -The corresponding settings in the ``update_submodule.sh`` file are the following: +The corresponding lines in the ``update_submodule.sh`` file are the following: -.. code-block:: bash +.. code-block:: bash - monitoring_root="${project_root}/modules/metrics/doc/monitoring" # - monitoring_dest="${project_root}/doc/book" + 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}/" + mkdir -p "${monitoring_dest}" + yes | cp -rf "${monitoring_root}" "${monitoring_dest}/" The ``${project_root}`` variable is defined earlier as ``project_root=$(pwd)``. We should start the documentation build from the documentation repository root @@ -109,28 +109,26 @@ In the final documentation view, the content should appear here: So, we need to: -* in ``/doc/book/cartridge``of the documentation repository, create - the ``/cartridge_cli`` sub-directory -* copy the ``README.rst`` file from the submodule - repository to the ``/doc/book/cartridge/cartridge_cli`` directory of the - documentation repository and rename it to ``index.rst``. +* create a directory at ``./doc/book/cartridge/cartridge_cli`` +* copy ``./modules/cartridge_cli/README.rst`` to + ``./doc/book/cartridge/cartridge_cli/index.rst``. The corresponding settings in the ``update_submodule.sh`` file are the following: -.. code-block:: bash +.. code-block:: bash - 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" + 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}" + mkdir -p "${cartridge_cli_dest}" + yes | cp -rf "${cartridge_cli_root}/README.rst" "${cartridge_cli_index_dest}" .. _guidelines_doc_submodules_gitignore: -Updating ``.gitignore`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +3. Update ``.gitignore`` +~~~~~~~~~~~~~~~~~~~~~~~~ Finaly, we should add paths to the copied directories and files to the ``.gitignore`` file.