Tarantool documentation source, published at https://www.tarantool.io/doc/.

First of all, pull the image for building the docs.

docker pull tarantool/doc-builder

Next, initialize a Makefile for your OS:

docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "cmake ."

A big part of documentation sources comes from several other projects, connected as Git submodules. To include their latest contents in the docs, run these two steps.

1. Update the submodules:

   docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make pull-modules"

   This will initialize Git submodules and update them to the top of the stable branch in each repository.

   You can also do without a Docker container:

   git submodule update --init
   git fetch --recurse-submodules
   git submodule update --remote --checkout

   git submodule update can sometimes fail, for example, when you have changes in submodules' files. You can reinitialize submodules to fix the problem.

   Caution: all untracked changes in submodules will be lost!

   ```bash
   git submodule deinit -f .
   git submodule update --init
   ```
   

2. Build the submodules content:

   docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make build-modules"

   This command will do two things:

   1. Generate documentation source files from the source code
   2. Copy these files to the right places under the ./doc/ directory.

   If you're editing submodules locally, repeat this step to view the updated results.

Now you're ready to build and preview the documentation locally.

When editing the documentation, you can set up a live-reload server. It will build your documentation and serve it on 127.0.0.1:8000. Every time you make changes in the source files, it will rebuild the docs and refresh the browser page.

docker run --rm -it -p 8000:8000 -v $(pwd):/doc tarantool/doc-builder sh -c "make autobuild"

First build will take some time. When it's done, open 127.0.0.1:8000 in the browser. Now when you make changes, they will be rebuilt in a few seconds, and the browser tab with preview will reload automatically.

You can also build the docs manually with make html, and then serve them using python3 built-in server:

docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make html"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make html-ru"
python3 -m http.server --directory output/html

or python2 built-in server:

cd output/html
python -m SimpleHTTPServer

then go to localhost:8000 in your browser.

There are other commands which can run in the tarantool/doc-builder container:

docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make html"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make html-ru"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make singlehtml"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make singlehtml-ru"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make pdf"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make pdf-ru"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make json"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make json-ru"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make epub"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make epub-ru"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make update-pot"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make update-po"
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make update-po-force"

Terms:

• translation unit (TU) is an atomic piece of text which can be translated. A paragraph, a list item, a heading, image's alt-text and so on.

• translation source files are the files with translation units in English only. They're located in locale/en.

• translation files are the files which match original text to translated text. They're located in locale/ru.

We use Crowdin for continuous localization. To work with Crowdin CLI, issue an API token in your account settings. Save it in ~/.crowdin.yml:

"api_token": "asdfg12345..."

Upload translation sources any time when they have changed:

# first, update the translation sources
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make update-pot"

# next, upload them to Crowdin
crowdin upload 
# or
crowdin upload sources

Upload translation files once for each project, to pass the existing translations to Crowdin:

crowdin upload translations --auto-approve-imported --import-eq-suggestions

Download translations files back when they're done. Then reformat them to see the real changes.

crowdin download
docker run --rm -it -v $(pwd):/doc tarantool/doc-builder sh -c "make reformat-po"

To contribute to documentation, use the REST format for drafting and submit your updates as a pull request via GitHub.

To comply with the writing and formatting style, use the guidelines provided in the documentation, common sense and existing documents.

Notes:

• If you suggest creating a new documentation section (a whole new page), it has to be saved to the relevant section at GitHub.

• If you want to contribute to localizing this documentation (for example into Russian), add your translation strings to .po files stored in the corresponding locale directory (for example /locale/ru/LC_MESSAGES/ for Russian). See more about localizing with Sphinx at http://www.sphinx-doc.org/en/stable/intl.html