Set up a live-reload server with make autobuild (#1855)

Author: NickVolynkin

CMakeLists.txt

@@ -71,6 +71,7 @@ set(SPHINX_BUILD_JSON_EN_DIR       "${SPHINX_OUTPUT_DIR}/json/_build_en/doctrees
 set(SPHINX_BUILD_JSON_RU_DIR       "${SPHINX_OUTPUT_DIR}/json/_build_ru/doctrees")
 
 set(SPHINX_EN_HTML_DIR             "${SPHINX_OUTPUT_DIR}/html/en/")
+set(SPHINX_EN_AUTOBUILD_DIR        "${SPHINX_OUTPUT_DIR}/html_auto/en/")
 set(SPHINX_RU_HTML_DIR             "${SPHINX_OUTPUT_DIR}/html/ru/")
 set(SPHINX_EN_HTML_OLD_DIR         "${SPHINX_OUTPUT_DIR}/html_old/en/")
 set(SPHINX_RU_HTML_OLD_DIR         "${SPHINX_OUTPUT_DIR}/html_old/ru/")
@@ -128,6 +129,19 @@ add_custom_target(singlehtml-website
     COMMENT "Building HTML single-page documentation with Sphinx"
 )
 
+add_custom_target(autobuild
+    COMMAND sphinx-autobuild
+        -b html
+        -d "${SPHINX_BUILD_HTML_DIR}"
+        -c html/
+        --host 0.0.0.0
+        --port 8000
+        -A nolang_path=true
+        "${CMAKE_CURRENT_SOURCE_DIR}/doc"
+        "${SPHINX_EN_AUTOBUILD_DIR}"
+    COMMENT "Build & Live-reload on https://127.0.0.1:8000"
+)
+
 add_custom_target(html-ru ALL
     COMMAND "${SPHINX_EXECUTABLE}"
         -b html

README.md

@@ -7,6 +7,7 @@ Tarantool documentation source, published at https://www.tarantool.io/doc/.
 ## How to build Tarantool documentation using [Docker](https://www.docker.com)
 
 ### Build docker image
+
 ```bash
 docker build -t tarantool-doc-builder .
 ```
@@ -38,7 +39,44 @@ Init make commands:
 docker run --rm -it -v $(pwd):/doc tarantool-doc-builder sh -c "cmake ."
 ```
 
-Run a required make command inside *tarantool-doc-builder* container:
+Now you're ready to build and preview the documentation locally.
+
+### Build and run the documentation on your machine
+
+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](http://127.0.0.1:8000).
+Every time you make changes in the source files, it will rebuild the docs
+and refresh the browser page.
+
+```bash
+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](http://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:
+```bash
+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:
+```bash
+cd output/html
+python -m SimpleHTTPServer
+```
+
+then go to [localhost:8000](http://localhost:8000) in your browser.
+
+
+There are other commands which can run 
+in the *tarantool-doc-builder* container:
+
 ```bash
 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"
@@ -55,19 +93,6 @@ 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"
 ```
 
-### Run documentation locally on your machine
-using python3 built-in server:
-```bash
-cd output/html
-python3 -m http.server
-```
-or python2 built-in server:
-```bash
-cd output/html
-python -m SimpleHTTPServer
-```
-then go to [localhost:8000](http://localhost:8000) in your browser.
-
 ## Localization
 
 Terms:

_theme/tarantool/elements.html

@@ -6,6 +6,8 @@
 {%- macro abspath(path) -%}
     {%- if rel_path == "true" -%}
         {{ path }}
+    {%- elif nolang_path == "true" -%}
+        {{ [ "/", path ] | join('') }}
     {%- else -%}
         {{ [ "/", language, "/", path ] | join('') }}
     {%- endif -%}

requirements.txt

@@ -2,4 +2,5 @@ Sphinx==1.8.5
 sphinx-intl
 lupa
 docutils==0.14
-sphinxcontrib-svg2pdfconverter
+sphinxcontrib-svg2pdfconverter
+sphinx-autobuild