From 5b74afe1e3ed45c29cbce29475ca14dcfe42207e Mon Sep 17 00:00:00 2001 From: Patience Daur Date: Tue, 5 Apr 2022 11:20:38 +0300 Subject: [PATCH 1/6] Add tracing as a submodule --- .gitmodules | 3 +++ modules/tracing | 1 + 2 files changed, 4 insertions(+) create mode 160000 modules/tracing diff --git a/.gitmodules b/.gitmodules index 3efe9f8560..13228360f4 100644 --- a/.gitmodules +++ b/.gitmodules @@ -19,3 +19,6 @@ [submodule "modules/tntcxx"] path = modules/tntcxx url = https://github.com/tarantool/tntcxx.git +[submodule "modules/tracing"] + path = modules/tracing + url = https://github.com/tarantool/tracing diff --git a/modules/tracing b/modules/tracing new file mode 160000 index 0000000000..0b5d7d2560 --- /dev/null +++ b/modules/tracing @@ -0,0 +1 @@ +Subproject commit 0b5d7d2560d5c5feca286cdb8145cbdbd6e2ca34 From 1476062248a73e541939efbba7fbfc448aedbe1d Mon Sep 17 00:00:00 2001 From: Patience Daur Date: Tue, 5 Apr 2022 13:40:12 +0300 Subject: [PATCH 2/6] Integrate tracing module doc - Submodule builder now pulls content from the tracing submodule - Git now ignores content pulled while building the docs - Add an overview page for tracing, accessible from the rocks reference index https://github.com/tarantool/doc/pull/1614/files does something similar. --- .gitignore | 6 ++++++ build_submodules.sh | 16 ++++++++++++++++ doc/reference/reference_rock/index.rst | 11 ++++++----- .../reference_rock/luatest/luatest_overview.rst | 8 ++++---- .../reference_rock/tracing_overview.rst | 10 ++++++++++ 5 files changed, 42 insertions(+), 9 deletions(-) create mode 100644 doc/reference/reference_rock/tracing_overview.rst diff --git a/.gitignore b/.gitignore index d248b8e00e..12cd851d9d 100644 --- a/.gitignore +++ b/.gitignore @@ -74,3 +74,9 @@ locale/* /doc/getting_started/getting_started_cxx.rst /doc/getting_started/_includes/ /doc/book/connectors/cxx/ + +# tracing submodule: leaving only tracing_overview + +/doc/reference/reference_rock/tracing/ +/locale/en/reference/reference_rock/tracing/ +/locale/ru/LC_MESSAGES/reference/reference_rock/tracing/ diff --git a/build_submodules.sh b/build_submodules.sh index 40dc39f176..9efe6be2eb 100755 --- a/build_submodules.sh +++ b/build_submodules.sh @@ -107,3 +107,19 @@ mkdir -p "${tntcxx_gs_dest}/_includes" yes | cp -rf "${tntcxx_root}/doc/tntcxx_getting_started.rst" "${tntcxx_gs_dest}/getting_started_cxx.rst" yes | cp -rf "${tntcxx_root}/examples/" "${tntcxx_gs_dest}/_includes/examples/" yes | cp -rf "${tntcxx_root}/doc/tntcxx_api.rst" "${tntcxx_api_dest}/cxx/" + + +# Tracing module +tracing_root="${project_root}/modules/tracing" +tracing_dest="${project_root}/doc/reference/reference_rock/tracing" + +# Generate tracing docs +cd "${tracing_root}" +ldoc --ext=rst --dir=rst --toctree="API" . + +# Copy tracing docs to the right place +mkdir -p "${tracing_dest}/_includes/" +yes | cp -fa "${tracing_root}/rst/." "${tracing_dest}" +pandoc -f gfm -t rst -o "${tracing_dest}/_includes/readme.rst" "${tracing_root}/README.md" +yes | mv -f "${tracing_dest}/index.rst" "${tracing_dest}/_includes/" +# TODO delete topics diff --git a/doc/reference/reference_rock/index.rst b/doc/reference/reference_rock/index.rst index 7282555e69..03ed5dc2de 100644 --- a/doc/reference/reference_rock/index.rst +++ b/doc/reference/reference_rock/index.rst @@ -7,12 +7,13 @@ Rocks reference This reference covers third-party Lua modules for Tarantool. -.. toctree:: - :maxdepth: 2 +.. toctree:: + :maxdepth: 1 - dbms + Module cartridge expirationd + Module luatest membership + Module tracing vshard/index - ../../book/cartridge/index - luatest/luatest_overview + dbms diff --git a/doc/reference/reference_rock/luatest/luatest_overview.rst b/doc/reference/reference_rock/luatest/luatest_overview.rst index ba1403ff3f..ab6bd11e97 100644 --- a/doc/reference/reference_rock/luatest/luatest_overview.rst +++ b/doc/reference/reference_rock/luatest/luatest_overview.rst @@ -1,6 +1,5 @@ -********************** -Luatest -********************** +Module luatest +============== More about Luatest API see :ref:`below `. @@ -8,4 +7,5 @@ More about Luatest API see :ref:`below `. .. _luatest-api: -.. include:: _includes/index.rst \ No newline at end of file +.. include:: _includes/index.rst + \ No newline at end of file diff --git a/doc/reference/reference_rock/tracing_overview.rst b/doc/reference/reference_rock/tracing_overview.rst new file mode 100644 index 0000000000..5cb4182071 --- /dev/null +++ b/doc/reference/reference_rock/tracing_overview.rst @@ -0,0 +1,10 @@ +Module tracing +============== + +More about ``tracing`` API see :ref:`below `. + +.. include:: tracing/_includes/readme.rst + +.. _tracing-api: + +.. include:: tracing/_includes/index.rst From b48173cdbf511987b3f1b69839a2d99194a7aef6 Mon Sep 17 00:00:00 2001 From: Patience Daur Date: Wed, 6 Apr 2022 09:11:57 +0300 Subject: [PATCH 3/6] Remove duplicate Tracing header from the toctree --- build_submodules.sh | 2 ++ 1 file changed, 2 insertions(+) diff --git a/build_submodules.sh b/build_submodules.sh index 9efe6be2eb..3dde13ad60 100755 --- a/build_submodules.sh +++ b/build_submodules.sh @@ -122,4 +122,6 @@ mkdir -p "${tracing_dest}/_includes/" yes | cp -fa "${tracing_root}/rst/." "${tracing_dest}" pandoc -f gfm -t rst -o "${tracing_dest}/_includes/readme.rst" "${tracing_root}/README.md" yes | mv -f "${tracing_dest}/index.rst" "${tracing_dest}/_includes/" +# remove header from included file +sed -i '1,3d' "${tracing_dest}/_includes/readme.rst" # TODO delete topics From df1e70223403ff48fb76dd2c64240e702c6ce4ab Mon Sep 17 00:00:00 2001 From: Patience Daur Date: Tue, 12 Apr 2022 09:40:21 +0300 Subject: [PATCH 4/6] Debug the API included file --- build_submodules.sh | 7 ++++--- doc/reference/reference_rock/tracing_overview.rst | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/build_submodules.sh b/build_submodules.sh index 3dde13ad60..48b15604cf 100755 --- a/build_submodules.sh +++ b/build_submodules.sh @@ -121,7 +121,8 @@ ldoc --ext=rst --dir=rst --toctree="API" . mkdir -p "${tracing_dest}/_includes/" yes | cp -fa "${tracing_root}/rst/." "${tracing_dest}" pandoc -f gfm -t rst -o "${tracing_dest}/_includes/readme.rst" "${tracing_root}/README.md" -yes | mv -f "${tracing_dest}/index.rst" "${tracing_dest}/_includes/" -# remove header from included file +yes | mv -f "${tracing_dest}/index.rst" "${tracing_dest}/_includes/api.rst" +# remove header from included README file sed -i '1,3d' "${tracing_dest}/_includes/readme.rst" -# TODO delete topics +# edit paths in the included API file +sed -i 's,modules,\.\.\/modules,g' "${tracing_dest}/_includes/api.rst" diff --git a/doc/reference/reference_rock/tracing_overview.rst b/doc/reference/reference_rock/tracing_overview.rst index 5cb4182071..9f07185917 100644 --- a/doc/reference/reference_rock/tracing_overview.rst +++ b/doc/reference/reference_rock/tracing_overview.rst @@ -7,4 +7,4 @@ More about ``tracing`` API see :ref:`below `. .. _tracing-api: -.. include:: tracing/_includes/index.rst +.. include:: tracing/_includes/api.rst From c59a136fab90f298e603e3737fa3ef3cc28f4970 Mon Sep 17 00:00:00 2001 From: Patience Daur Date: Wed, 13 Apr 2022 13:37:13 +0300 Subject: [PATCH 5/6] Make sphinx display the API toctree Seems like the usual addressing rules don't work in sphinx. I provided "incorrect" addresses that display correct results against all logic. Normally, a link like "tracing/modules/filename" in the toctree would lead you two levels down. However, when this kind of link is provided in a file in an `_includes` directory, it seems to jump one level up first and then go down the tree, ending up in the right place. At the same time, build logs show errors. Thus, an incorrect link, recognized by Sphinx as such, provides the right result when parsed. Error + error = no error. --- build_submodules.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/build_submodules.sh b/build_submodules.sh index 48b15604cf..d1bdac46b0 100755 --- a/build_submodules.sh +++ b/build_submodules.sh @@ -125,4 +125,5 @@ yes | mv -f "${tracing_dest}/index.rst" "${tracing_dest}/_includes/api.rst" # remove header from included README file sed -i '1,3d' "${tracing_dest}/_includes/readme.rst" # edit paths in the included API file -sed -i 's,modules,\.\.\/modules,g' "${tracing_dest}/_includes/api.rst" +# Addressing in sphinx includes sometimes defies common logic +sed -i 's,modules,tracing\/modules,g' "${tracing_dest}/_includes/api.rst" From ae3b267f1ba7b32f31faa472cf79cdf587bf60f4 Mon Sep 17 00:00:00 2001 From: Patience Daur Date: Thu, 14 Apr 2022 08:14:09 +0300 Subject: [PATCH 6/6] Add a dummy toctree So that the modules included in the tracing API, which is in an _included file, still display in the left menu. --- doc/reference/reference_rock/tracing_overview.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/reference/reference_rock/tracing_overview.rst b/doc/reference/reference_rock/tracing_overview.rst index 9f07185917..5f1ec3902b 100644 --- a/doc/reference/reference_rock/tracing_overview.rst +++ b/doc/reference/reference_rock/tracing_overview.rst @@ -8,3 +8,12 @@ More about ``tracing`` API see :ref:`below `. .. _tracing-api: .. include:: tracing/_includes/api.rst + +.. toctree:: + :maxdepth: 1 + + tracing/modules/opentracing + tracing/modules/opentracing.span + tracing/modules/opentracing.span_context + tracing/modules/opentracing.tracer + tracing/modules/zipkin.tracer