Use cmake for docs (#317)

Author: aobolensk

.github/workflows/pages.yml

@@ -21,24 +21,23 @@ jobs:
         with:
           python-version: '3.13'
       - name: Install dependencies
-        working-directory: ./docs
         run: |
-          python3 -m pip install -r requirements.txt
+          python3 -m pip install -r docs/requirements.txt
+      - name: Configure project
+        run: >
+          cmake -S . -B build -D USE_DOCS=ON
       - name: Build i18n
-        working-directory: ./docs
         run: |
-          make gettext
-          sphinx-build -b gettext . _build/gettext
-          sphinx-intl update -p _build/gettext -l en -l ru
+          cmake --build build -t docs_gettext
+          cmake --build build -t docs_update
       - name: Build documentation
-        working-directory: ./docs
         run: |
-          make html
+          cmake --build build -t docs_html
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
           name: sphinx-documentation
-          path: ./docs/_build/html
+          path: ./build/docs/_build/html
   build-scoreboard:
     runs-on: ubuntu-24.04
     steps:

CMakeLists.txt

@@ -24,6 +24,12 @@ message( STATUS "PPC step: Setup external projects" )
 include(cmake/opencv.cmake)
 include(cmake/gtest.cmake)
 
+########################### Documentation ###########################
+
+message( STATUS "PPC step: Setup documentation generation" )
+include(cmake/sphinx.cmake)
+add_subdirectory(docs)
+
 ############################ Scoreboard #############################
 
 message( STATUS "PPC step: Setup scoreboard generator" )

cmake/sphinx.cmake

@@ -0,0 +1,6 @@
+option(USE_DOCS OFF)
+if( USE_DOCS )
+    set(SPHINXBUILD "sphinx-build")
+    set(SPHINXINTL  "sphinx-intl")
+    set(SPHINXOPTS "-W" "--keep-going" "-n")
+endif( USE_DOCS )

docs/CMakeLists.txt

@@ -0,0 +1,37 @@
+if (NOT USE_DOCS)
+  return()
+endif()
+
+set(SOURCEDIR "${CMAKE_CURRENT_SOURCE_DIR}")
+set(BUILDDIR "${CMAKE_CURRENT_BINARY_DIR}/_build/html")
+set(GETTEXTDIR "${CMAKE_CURRENT_BINARY_DIR}/_build/gettext")
+
+add_custom_target(docs_help
+  COMMAND ${SPHINXBUILD} -M help "${SOURCEDIR}" "${BUILDDIR}/en" ${SPHINXOPTS}
+  WORKING_DIRECTORY "${SOURCEDIR}"
+  COMMENT "Displaying Sphinx Makefile help"
+)
+
+# 'gettext' target: generate gettext catalogs.
+add_custom_target(docs_gettext
+  COMMAND ${SPHINXBUILD} -b gettext "${SOURCEDIR}" "${GETTEXTDIR}" ${SPHINXOPTS}
+  WORKING_DIRECTORY "${SOURCEDIR}"
+  COMMENT "Generating gettext output"
+)
+
+# 'update' target: update translations for the specified languages.
+add_custom_target(docs_update
+  COMMAND ${SPHINXINTL} update -p "${GETTEXTDIR}" -l en -l ru
+  WORKING_DIRECTORY "${SOURCEDIR}"
+  COMMENT "Updating Sphinx translations"
+)
+
+# 'html' target: build the HTML documentation in both English and Russian.
+add_custom_target(docs_html
+  # Build English documentation.
+  COMMAND ${SPHINXBUILD} -b html -D language=en "${SOURCEDIR}" "${BUILDDIR}/en" ${SPHINXOPTS}
+  # Build Russian documentation.
+  COMMAND ${SPHINXBUILD} -b html -D language=ru "${SOURCEDIR}" "${BUILDDIR}/ru" ${SPHINXOPTS}
+  WORKING_DIRECTORY "${SOURCEDIR}"
+  COMMENT "Building HTML documentation for English and Russian"
+)

docs/Makefile

@@ -17,30 +17,35 @@ python3 -m venv venv
 pip install -r requirements.txt
 ```
 
-4. Build the documentation:
+4. Configure the documentation build:
 ```bash
-make html
+cmake -S . -B build -DUSE_DOCS=ON
 ```
 
-5. Update the documentation:
+5. Build the documentation:
 ```bash
-make gettext
+cmake --build build -t docs_html
+```
+
+6. Update the documentation:
+```bash
+cmake --build build -t docs_gettext
 # update documentation
-make update
+cmake --build build -t docs_update
 ```
 
-6. Re-build the documentation:
+7. Re-build the documentation:
 ```bash
-make html
+cmake --build build -t docs_html
 ```
 
-7. Make local deployment of the changes:
+8. Make local deployment of the changes:
 ```bash
 cd _build/html
 python3 -m http.server 8080
 ```
 
-8. Open the documentation in your browser:
+9. Open the documentation in your browser:
 ```bash
 open http://localhost:8080/en
 open http://localhost:8080/ru