Skip to content

Commit 590800c

Browse files
artemboartembo
committed
Pdf builder update
Changed :code: to :math: where formulas are used in rst sources, conf.py modified for proper math using CmakeLists modified to prevent errors during pdf build Actualized Dockerfile and readme for building documentation using docker Added tabularcolumns directive to fit table column size in pdf Removed empty pages in pdf
1 parent 2f8abd1 commit 590800c

16 files changed

+113
-67
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ output
1111
*.pyc
1212
_theme/tarantool/static/design.css.map
1313
.*.swp
14+
.idea

‎CMakeLists.txt

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -159,14 +159,18 @@ if (LATEX_FOUND)
159159
-Dlanguage=ru
160160
)
161161
add_custom_command(TARGET sphinx-pdf-ru
162-
COMMAND "${PDFLATEX_COMPILER}" -interaction nonstopmode Tarantool.tex
162+
COMMAND "${PDFLATEX_COMPILER}" -interaction nonstopmode Tarantool.tex || true
163163
WORKING_DIRECTORY ${SPHINX_BUILD_LATEX_RU_DIR}
164164
)
165165
add_custom_command(TARGET sphinx-pdf-ru
166-
COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_RU_HTML_DIR}/doc/1.10/)
166+
COMMAND "${PDFLATEX_COMPILER}" -interaction nonstopmode Tarantool.tex || true
167+
WORKING_DIRECTORY ${SPHINX_BUILD_LATEX_RU_DIR}
168+
)
167169
add_custom_command(TARGET sphinx-pdf-ru
168-
COMMAND ${CMAKE_COMMAND} -E copy ${SPHINX_BUILD_LATEX_RU_DIR}/Tarantool.pdf
169-
${SPHINX_RU_HTML_DIR}/doc/1.10/)
170+
COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_RU_HTML_DIR}doc/1.10/)
171+
add_custom_command(TARGET sphinx-pdf-ru
172+
COMMAND ${CMAKE_COMMAND} -E copy ${SPHINX_BUILD_LATEX_RU_DIR}Tarantool.pdf
173+
${SPHINX_RU_HTML_DIR}doc/1.10/)
170174

171175
add_custom_target(sphinx-pdf ALL COMMENT "PDF generation")
172176
add_custom_command(TARGET sphinx-pdf
@@ -177,16 +181,19 @@ if (LATEX_FOUND)
177181
"${CMAKE_CURRENT_SOURCE_DIR}"
178182
"${SPHINX_BUILD_LATEX_DIR}"
179183
)
180-
181184
add_custom_command(TARGET sphinx-pdf
182-
COMMAND "${PDFLATEX_COMPILER}" -interaction nonstopmode Tarantool.tex
185+
COMMAND "${PDFLATEX_COMPILER}" -interaction nonstopmode Tarantool.tex || true
186+
WORKING_DIRECTORY ${SPHINX_BUILD_LATEX_DIR}
187+
)
188+
add_custom_command(TARGET sphinx-pdf
189+
COMMAND "${PDFLATEX_COMPILER}" -interaction nonstopmode Tarantool.tex || true
183190
WORKING_DIRECTORY ${SPHINX_BUILD_LATEX_DIR}
184191
)
185192
add_custom_command(TARGET sphinx-pdf
186-
COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_EN_HTML_DIR}/doc/1.10/)
193+
COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_EN_HTML_DIR}doc/1.10/)
187194
add_custom_command(TARGET sphinx-pdf
188-
COMMAND ${CMAKE_COMMAND} -E copy ${SPHINX_BUILD_LATEX_DIR}/Tarantool.pdf
189-
${SPHINX_EN_HTML_DIR}/doc/1.10/)
195+
COMMAND ${CMAKE_COMMAND} -E copy ${SPHINX_BUILD_LATEX_DIR}Tarantool.pdf
196+
${SPHINX_EN_HTML_DIR}doc/1.10/)
190197
endif()
191198

192199
add_custom_target(sphinx-webserver

‎Dockerfile

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
FROM packpack/packpack:ubuntu-xenial
1+
FROM artembo/python-texlive:latest
22

3-
COPY requirements.txt /requirements.txt
3+
RUN pip install Sphinx==1.8.5 sphinx-intl lupa docutils==0.14
44

5-
RUN apt-get update && apt-get -y install pkg-config lua5.1-dev python-pip python-setuptools python-dev texlive texlive-latex-extra xzdec texlive-lang-cyrillic imagemagick librsvg2-bin
6-
7-
RUN pip install -r /requirements.txt --upgrade
5+
RUN mkdir /doc
6+
WORKDIR /doc

‎README.md

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,38 @@
11
# doc
2-
Tarantool web site and documentation
2+
Tarantool documentation
3+
4+
## How to build Tarantool documentation using [Docker](https://www.docker.com)
5+
6+
### Build docker image
7+
```bash
8+
docker build -t tarantool-doc-builder .
9+
```
10+
11+
### Build Tarantool documentation using *tarantool-doc-builder* image
12+
13+
Init make commands:
14+
```bash
15+
docker run --rm -it -v $(pwd):/doc tarantool-doc-builder sh -c "cmake ."
16+
```
17+
Run a required make command inside *tarantool-doc-builder* container:
18+
```bash
19+
docker run --rm -it -v $(pwd):/doc tarantool-doc-builder sh -c "make sphinx-html"
20+
docker run --rm -it -v $(pwd):/doc tarantool-doc-builder sh -c "make sphinx-html-ru"
21+
docker run --rm -it -v $(pwd):/doc tarantool-doc-builder sh -c "make sphinx-singlehtml"
22+
docker run --rm -it -v $(pwd):/doc tarantool-doc-builder sh -c "make sphinx-singlehtml-ru"
23+
docker run --rm -it -v $(pwd):/doc tarantool-doc-builder sh -c "make sphinx-pdf"
24+
docker run --rm -it -v $(pwd):/doc tarantool-doc-builder sh -c "make sphinx-pdf-ru"
25+
```
26+
27+
### Run documentation locally on your machine
28+
using python3 built-in server:
29+
```bash
30+
cd output
31+
python3 -m http.server
32+
```
33+
or python2 built-in server:
34+
```bash
35+
cd output
36+
python -m SimpleHTTPServer
37+
```
38+
then go to [localhost:8000](http://localhost:8000) in your browser.

‎conf.py

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,9 @@
3131
'ext.ModuleBlock',
3232
'ext.DownloadPageBlock'
3333
]
34+
35+
imgmath_image_format = 'svg'
36+
3437
primary_domain = 'lua'
3538
source_suffix = '.rst'
3639

@@ -195,7 +198,9 @@
195198
}
196199

197200
latex_elements = {
198-
'fontenc': r'\usepackage[T1,T2A]{fontenc}'
201+
'fontenc': r'\usepackage[T1,T2A]{fontenc}',
202+
'hyperref': r'\usepackage[pdftex,pagebackref=true,backref=true,bookmarksopenlevel=1,colorlinks=true,linkcolor=blue,filecolor=magenta,urlcolor=cyan]{hyperref}',
203+
'extraclassoptions': 'openany',
199204
}
200205

201206
intersphinx_cache_limit = 0

‎doc/1.10/book/box/box_index.rst

Lines changed: 13 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -210,6 +210,8 @@ Below is a list of all ``box.index`` functions and members.
210210
.. rst-class:: left-align-column-2
211211
.. rst-class:: left-align-column-3
212212

213+
.. tabularcolumns:: |\Y{0.2}|\Y{0.2}|\Y{0.6}|
214+
213215
+---------------+-----------+---------------------------------------------+
214216
| Type | Arguments | Description |
215217
+===============+===========+=============================================+
@@ -307,6 +309,8 @@ Below is a list of all ``box.index`` functions and members.
307309
.. rst-class:: left-align-column-2
308310
.. rst-class:: left-align-column-3
309311

312+
.. tabularcolumns:: |\Y{0.2}|\Y{0.2}|\Y{0.6}|
313+
310314
+---------------+-----------+------------------------------------------------+
311315
| Type | Arguments | Description |
312316
+===============+===========+================================================+
@@ -341,6 +345,8 @@ Below is a list of all ``box.index`` functions and members.
341345
.. rst-class:: left-align-column-2
342346
.. rst-class:: left-align-column-3
343347

348+
.. tabularcolumns:: |\Y{0.4}|\Y{0.2}|\Y{0.4}|
349+
344350
+----------------------------+-----------+----------------------------------------------+
345351
| Type | Arguments | Description |
346352
+============================+===========+==============================================+
@@ -377,50 +383,13 @@ Below is a list of all ``box.index`` functions and members.
377383
.. rst-class:: left-align-column-2
378384
.. rst-class:: left-align-column-3
379385

380-
+--------------------+-----------+---------------------------------------------------------+
381-
| Type | Arguments | Description |
382-
+====================+===========+=========================================================+
383-
| box.index.ALL | none | All keys match. |
384-
| or 'ALL' | | Tuples are returned in their order within the space. |
385-
+--------------------+-----------+---------------------------------------------------------+
386-
| box.index.EQ | search | If all points of the rectangle-or-box defined by the |
387-
| or 'EQ' | value | search value are the same as the rectangle-or-box |
388-
| | | defined by the index key, it matches. |
389-
| | | Tuples are returned in their order within the space. |
390-
| | | "Rectangle-or-box" means "rectangle-or-box as |
391-
| | | explained in section about |
392-
| | | :ref:`RTREE <box_index-rtree>`". This is the default. |
393-
+--------------------+-----------+---------------------------------------------------------+
394-
| box.index.GT | search | If all points of the rectangle-or-box defined by the |
395-
| or 'GT' | value | search value are within the rectangle-or-box |
396-
| | | defined by the index key, it matches. |
397-
| | | Tuples are returned in their order within the space. |
398-
+--------------------+-----------+---------------------------------------------------------+
399-
| box.index.GE | search | If all points of the rectangle-or-box defined by the |
400-
| or 'GE' | value | search value are within, or at the side of, the |
401-
| | | rectangle-or-box defined by the index key, it matches. |
402-
| | | Tuples are returned in their order within the space. |
403-
+--------------------+-----------+---------------------------------------------------------+
404-
| box.index.LT | search | If all points of the rectangle-or-box defined by the |
405-
| or 'LT' | value | index key are within the rectangle-or-box |
406-
| | | defined by the search key, it matches. |
407-
| | | Tuples are returned in their order within the space. |
408-
+--------------------+-----------+---------------------------------------------------------+
409-
| box.index.LE | search | If all points of the rectangle-or-box defined by the |
410-
| or 'LE' | value | index key are within, or at the side of, the |
411-
| | | rectangle-or-box defined by the search key, it matches. |
412-
| | | Tuples are returned in their order within the space. |
413-
+--------------------+-----------+---------------------------------------------------------+
414-
| box.index.OVERLAPS | search | If some points of the rectangle-or-box defined by the |
415-
| or 'OVERLAPS' | values | search value are within the rectangle-or-box |
416-
| | | defined by the index key, it matches. |
417-
| | | Tuples are returned in their order within the space. |
418-
+--------------------+-----------+---------------------------------------------------------+
419-
| box.index.NEIGHBOR | search | If some points of the rectangle-or-box defined by the |
420-
| or 'NEIGHBOR' | value | defined by the key are within, or at the side of, |
421-
| | | defined by the index key, it matches. |
422-
| | | Tuples are returned in order: nearest neighbor first. |
423-
+--------------------+-----------+---------------------------------------------------------+
386+
.. tabularcolumns:: |\Y{0.3}|\Y{0.2}|\Y{0.5}|
387+
388+
.. csv-table::
389+
:file: box_index_rtree.csv
390+
:class: longtable
391+
:header-rows: 1
392+
:delim: 0x3B
424393

425394
**First example of index pairs():**
426395

‎doc/1.10/book/box/box_index_rtree.csv

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Type;Arguments;Description
2+
box.index.ALL or 'ALL';none;All keys match. Tuples are returned in their order within the space.
3+
box.index.EQ or 'EQ';search value;If all points of the rectangle-or-box defined by the search value are the same as the rectangle-or-box defined by the index key, it matches. Tuples are returned in their order within the space. "Rectangle-or-box" means "rectangle-or-box as explained in section about :ref:`RTREE <box_index-rtree>`". This is the default.
4+
box.index.GT or 'GT';search value;If all points of the rectangle-or-box defined by the search value are within the rectangle-or-box defined by the index key, it matches. Tuples are returned in their order within the space.
5+
box.index.GE or 'GE';search value;If all points of the rectangle-or-box defined by the search value are within, or at the side of, the rectangle-or-box defined by the index key, it matches. Tuples are returned in their order within the space.
6+
box.index.LT or 'LT';search value;If all points of the rectangle-or-box defined by the index key are within the rectangle-or-box defined by the search key, it matches. Tuples are returned in their order within the space.
7+
box.index.LE or 'LE';search value;If all points of the rectangle-or-box defined by the index key are within, or at the side of, the rectangle-or-box defined by the search key, it matches. Tuples are returned in their order within the space.
8+
box.index.OVERLAPS or 'OVERLAPS';search value;If some points of the rectangle-or-box defined by the search value are within the rectangle-or-box defined by the index key, it matches. Tuples are returned in their order within the space.
9+
box.index.NEIGHBOR or 'NEIGHBOR';search value;If some points of the rectangle-or-box defined by the defined by the key are within, or at the side of, defined by the index key, it matches. Tuples are returned in order: nearest neighbor first.

‎doc/1.10/book/box/box_schema.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,8 @@ Below is a list of all ``box.schema`` functions.
125125
.. rst-class:: left-align-column-3
126126
.. rst-class:: left-align-column-4
127127

128+
.. tabularcolumns:: |\Y{0.2}|\Y{0.4}|\Y{0.2}|\Y{0.2}|
129+
128130
+---------------+----------------------------------------------------+---------+---------------------+
129131
| Name | Effect | Type | Default |
130132
+===============+====================================================+=========+=====================+

‎doc/1.10/book/box/box_space.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -276,6 +276,8 @@ Below is a list of all ``box.space`` functions and members.
276276
.. rst-class:: left-align-column-3
277277
.. rst-class:: left-align-column-4
278278

279+
.. tabularcolumns:: |\Y{0.2}|\Y{0.3}|\Y{0.2}|\Y{0.3}|
280+
279281
+---------------------+-------------------------------------------------------+----------------------------------+-------------------------------+
280282
| Name | Effect | Type | Default |
281283
+=====================+=======================================================+==================================+===============================+
@@ -394,6 +396,8 @@ Below is a list of all ``box.space`` functions and members.
394396
.. rst-class:: left-align-column-4
395397
.. rst-class:: top-align-column-1
396398

399+
.. tabularcolumns:: |\Y{0.2}|\Y{0.4}|\Y{0.2}|\Y{0.2}|
400+
397401
+------------------+---------------------------+---------------------------------------+-------------------+
398402
| Index field type | What can be in it | Where is it legal | Examples |
399403
+------------------+---------------------------+---------------------------------------+-------------------+
@@ -1974,6 +1978,8 @@ Below is a list of all ``box.space`` functions and members.
19741978
.. rst-class:: left-align-column-3
19751979
.. rst-class:: left-align-column-4
19761980

1981+
.. tabularcolumns:: |\Y{0.2}|\Y{0.1}|\Y{0.1}|\Y{0.6}|
1982+
19771983
+-------------+----+------+----------------------------------------------------------------+
19781984
| Name | ID | Type | Description |
19791985
+=============+====+======+================================================================+

‎doc/1.10/book/box/box_txn_management.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,8 @@ Below is a list of all functions for transaction management.
4747
.. rst-class:: left-align-column-1
4848
.. rst-class:: left-align-column-2
4949

50+
.. tabularcolumns:: |\Y{0.4}|\Y{0.6}|
51+
5052
+--------------------------------------+---------------------------------+
5153
| Name | Use |
5254
+======================================+=================================+

‎doc/1.10/book/box/data_model.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -265,6 +265,8 @@ Here's how Tarantool indexed field types correspond to MsgPack data types.
265265
.. rst-class:: left-align-column-4
266266
.. rst-class:: top-align-column-1
267267

268+
.. tabularcolumns:: |\Y{0.2}|\Y{0.4}|\Y{0.2}|\Y{0.2}|
269+
268270
+----------------------------+----------------------------------+----------------------+--------------------+
269271
| Indexed field type | MsgPack data type |br| | Index type | Examples |
270272
| | (and possible values) | | |
@@ -446,6 +448,8 @@ Options for ``box.schema.sequence.create()``
446448
.. rst-class:: left-align-column-4
447449
.. rst-class:: top-align-column-1
448450

451+
.. tabularcolumns:: |\Y{0.2}|\Y{0.4}|\Y{0.2}|\Y{0.2}|
452+
449453
+----------------------------+----------------------------------+----------------------+--------------------+
450454
| Option name | Type and meaning | Default | Examples |
451455
+============================+==================================+======================+====================+

‎doc/1.10/book/box/engines/vinyl.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ that’s not larger than the key being searched (recall that elements at each
8484
level are sorted). If the first level yields no results, the search proceeds to
8585
the next level. Finally, the search ends up in one of the leaves and probably
8686
locates the needed key. Blocks are stored and read into RAM one by one, meaning
87-
the algorithm reads :code:`logB(N)` blocks in a single search, where N is the number of
87+
the algorithm reads :math:`logB(N)` blocks in a single search, where N is the number of
8888
elements in the B-tree. In the simplest case, writes are done similarly: the
8989
algorithm finds the block that holds the necessary element and updates (inserts)
9090
its value.
@@ -267,10 +267,10 @@ other hand, you need to minimize the compaction-related overhead, then the run
267267
size ratio can be decreased: the pyramid will grow higher, and even though runs
268268
will be compacted more often, they will be smaller, which will reduce the total
269269
amount of work done. In general, write amplification in an LSM tree is described
270-
by this formula: :code:`log_{x}(\frac {N} {L0}) × x` or, alternatively,
271-
:code:`x × \frac {ln (\frac {N} {C0})} {ln(x)}`, where N is
270+
by this formula: :math:`log_{x}(\frac {N} {L0}) × x` or, alternatively,
271+
:math:`x × \frac {ln (\frac {N} {C0})} {ln(x)}`, where N is
272272
the total size of all tree elements, L0 is the level zero size, and x is the
273-
level size ratio (the ``level_size_ratio`` parameter). At :code:`\frac {N} {C0}` = 40 (the disk-to-
273+
level size ratio (the ``level_size_ratio`` parameter). At :math:`\frac {N} {C0}` = 40 (the disk-to-
274274
memory ratio), the plot would look something like this:
275275

276276
.. image:: vinyl/curve.png
@@ -399,7 +399,7 @@ Disadvantages of an LSM tree and how to deal with them
399399
-------------------------------------------------------------------------------
400400

401401
One of the key advantages of the B-tree as a search data structure is its
402-
predictability: all operations take no longer than :code:`log_{B}(N)` to run.
402+
predictability: all operations take no longer than :math:`log_{B}(N)` to run.
403403
Conversely, in a classical LSM tree, both read and write speeds can differ by a
404404
factor of hundreds (best case scenario) or even thousands (worst case scenario).
405405
For example, adding just one element to L0 can cause it to overflow, which can

‎doc/1.10/reference/reference_lua/errcodes.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ descriptions of some popular codes. A complete list of errors can be found in fi
2020
.. rst-class:: left-align-column-1
2121
.. rst-class:: left-align-column-2
2222

23+
.. tabularcolumns:: |\Y{0.3}|\Y{0.7}|
24+
2325
+-------------------+--------------------------------------------------------+
2426
| ER_NONMASTER | (In replication) A server instance cannot modify data |
2527
| | unless it is a master. |

0 commit comments

Comments
 (0)