Рейтинг@Mail.ru

Building documentation

Замечание

Документация находится в процессе перевода и может отставать от английской версии.

Building documentation

Tarantool documentation is built using a simplified markup system named Sphinx (see http://sphinx-doc.org). You can build a local version of this documentation and you can contribute to Tarantool’s version.

You need to install these packages:

  • git (a program for downloading source repositories)
  • CMake version 2.8 or later (a program for managing the build process)
  • Python version greater than 2.6 – preferably 2.7 – and less than 3.0 (Sphinx is a Python-based tool)
  • LaTeX (a system for document preparation; the installable package name usually begins with the word „texlive“ or „tetex“, on Ubuntu the name is „texlive-latex-base“)
  • ImageMagick (a system for image conversion; on MacOS install it using brew)

You need to install these Python modules:

See more details about installation in the build-from-source section of this documentation.

  1. Use git to download the latest source code of this documentation from the GitHub repository tarantool/doc, branch 1.7. For example, to download to a local directory named ~/tarantool-doc:

    $ git clone https://github.com/tarantool/doc.git ~/tarantool-doc
    
  2. Use CMake to initiate the build.

    $ cd ~/tarantool-doc
    $ make clean         # unnecessary, added for good luck
    $ rm CMakeCache.txt  # unnecessary, added for good luck
    $ cmake .            # initiate
    
  3. Build a local version of the documentation.

    Run the make command with an appropriate option to specify which documentation version to build.

    $ cd ~/tarantool-doc
    $ make sphinx-html           # multi-page English version
    $ make sphinx-singlehtml     # one-page English version
    $ make sphinx-html-ru        # multi-page Russian version
    $ make sphinx-singlehtml-ru  # one-page Russian version
    $ make all                   # all versions plus the entire web-site
    

    Documentation will be created in subdirectories of /output:

    • /output/en (files of the English version)
    • /output/ru (files of the Russian version)

    The entry point for each version is the index.html file in the appropriate directory.

  4. Set up a web server.

    • One way is to say make sphinx-webserver. This will set up and run the web server on port 8000:

      $ cd ~/tarantool-doc
      $ make sphinx-html       # as an example, build the multi-page English documentation
      $ make sphinx-webserver  # set up and run the web server
      

      In case port 8000 is already in use, you can specify any other port number that is bigger than 1000 in the tarantool-doc/CMakeLists.txt file (search it for the sphinx-webserver target) and rebuild cmake files:

      $ cd ~/tarantool-doc
      $ git clean -qfxd        # clean up old cmake files
      $ cmake .                # rebuild cmake files
      $ make sphinx-html       # as an example, build the multi-page English documentation
      $ make sphinx-webserver  # set up and run the web server on the custom port
      

      Or you can release the port:

      $ sudo lsof -i :8000  # get the process ID (PID)
      COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
      Python 19516 user 3u IPv4 0xe7f8gc6be1b43c7 0t0 TCP *:irdmi (LISTEN)
      $ sudo kill -9 19516  # kill the process
      
    • The other way is to run the built-in web server in Python. Make sure to run it from the documentation output folder:

      $ cd ~/tarantool-doc/output
      $ python -m SimpleHTTPServer 8000
      

      In case port 8000 is already in use, you can specify any other port number that is bigger than 1000.

  5. Open your browser and enter 127.0.0.1:8000/en/doc/1.7/ into the address box (or 127.0.0.1:8000/ru/doc/1.7/ if you built the Russian documentation). Mind the trailing slash «/» in the address string.

    If your local documentation build is valid, the manual will appear in the browser.

  6. 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.

Примечание

  • 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