meson: generate doc with a run target

diff --git a/.gitignore b/.gitignore
index a2e0d8aba573fbb08193434ff89fc354b3f13b30..94a8d973c6025bbd1d2492bb19b0a909a5ec0097 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -46,6 +46,7 @@
 /daemon/lua/trust_anchors.lua
 /depcomp
 /distro/tests/*/.vagrant
+/doc/.doctrees
 /doc/doxyxml
 /doc/html
 /doc/kresd.8

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index ec00ea4176c0a1d18989faeef35403eeb3739a8a..16f7124bf586e4048b3426cbe1520dd796f1b4e3 100644 (file)
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -123,6 +123,14 @@ kres-gen:
     when:
       - script_failure
 
+.test_nodep: &test_nodep
+  stage: test
+  except:
+    - master
+  dependencies: []  # do not download build artifacts
+  tags:
+    - docker
+
 lint:pedantic:
   stage: test  # could be in build already, but let's not block the test stage if this fails
   dependencies: []  # do not download build artifacts
@@ -194,18 +202,14 @@ docker:
     - docker rmi $(docker images -f "dangling=true" -q)
 
 doc:
-  stage: test
-  except:
-    - master
+  <<: *test_nodep
   script:
-    - SPHINXFLAGS="-W" make doc
-  dependencies: []
+    - meson build_doc -Ddoc=enabled
+    - ninja -C build_doc doc
   artifacts:
     expire_in: 1 hour
     paths:
-      - ./doc/*
-  tags:
-    - docker
+      - doc/html
 
 deckard:
   <<: *test_flaky

diff --git a/distro/arch/PKGBUILD b/distro/arch/PKGBUILD
index 959dd070a7ab0ae9390ed9415901334f0cd18764..bb0cb497d7de0401ade5c8739605fe7da6b9006d 100644 (file)
--- a/distro/arch/PKGBUILD
+++ b/distro/arch/PKGBUILD
@@ -25,10 +25,7 @@ depends=(
 )
 makedepends=(
     'cmocka'
-    'doxygen'
     'meson'
-    'python-sphinx'
-    'python-breathe'
     'systemd-libs'
 )
 

diff --git a/distro/deb/rules b/distro/deb/rules
index 43d36da38411692172913ed8c033acae943c4d49..f0a3d7e275a3f69b23b399066a8846f9909c2e8d 100755 (executable)
--- a/distro/deb/rules
+++ b/distro/deb/rules
@@ -33,6 +33,7 @@ override_dh_auto_build:
                -Dc_args="$${CFLAGS}" \
                -Dc_link_args="$${LDFLAGS}"
        ninja -v -C build_deb
+       ninja -v -C build_deb doc
 
 override_dh_auto_install:
        DESTDIR="${PWD}/debian/tmp" ninja -v -C build_deb install

diff --git a/distro/rpm/knot-resolver.spec b/distro/rpm/knot-resolver.spec
index 49d2b71fd7ffbb20c98349ce65d463bace9d62af..c2b76e38a711fd5227223cccadbe902f6890ec26 100644 (file)
--- a/distro/rpm/knot-resolver.spec
+++ b/distro/rpm/knot-resolver.spec
@@ -138,6 +138,9 @@ meson build_rpm \
     -Dc_link_args="%{?__global_ldflags}"
 
 ninja-build -v -C build_rpm
+%if "x%{?rhel}" == "x"
+ninja-build -v -C build_rpm doc
+%endif
 
 %check
 meson test -C build_rpm

diff --git a/doc/build.rst b/doc/build.rst
index 5f9b22e353de50fd988e6e9e9ceb066d34290993..59ffdf599fef5a3535c37fcba6f4fc1a4700dfaa 100644 (file)
--- a/doc/build.rst
+++ b/doc/build.rst
@@ -197,6 +197,20 @@ It's also possible to run only specific test suite or a test.
    $ meson test -C build_test --no-suite postinstall
    $ meson test -C build_test integration.serve_stale
 
+.. _build-html-doc:
+
+HTML Documentation
+------------------
+
+To check for documentation dependencies and allow its installation, use
+``-Ddoc=enabled``. The documentation doesn't build automatically. Instead,
+target ``doc`` must be called explicitly.
+
+.. code-block:: bash
+
+   $ meson build_doc -Ddoc=enabled
+   $ ninja -C build_doc doc
+
 Tarball
 -------
 
@@ -223,7 +237,7 @@ Recommended build options for packagers:
 * ``--prefix=/usr`` to customize
   prefix, other directories can be set in a similar fashion, see ``meson setup
   --help``
-* ``-Ddoc=enabled`` for offline html documentation
+* ``-Ddoc=enabled`` for offline html documentation (see :ref:`build-html-doc`)
 * ``-Dinstall_kresd_conf=enabled`` to install default config file
 * ``-Dclient=enabled`` to force build of kresc
 * ``-Dunit_tests=enabled`` to force build of unit tests

diff --git a/doc/meson.build b/doc/meson.build
index c39a71ca96e6bd896efffad1778c4bdb6df28cb4..4e72499c3641c75819b7b059fddf0b7815cfe402 100644 (file)
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -16,8 +16,8 @@ man_kresd = configure_file(
 install_man(man_kresd)
 
 
-build_doc = get_option('doc').enabled()  # NOTE 'auto' unsupported
-if build_doc  # doxygen + html docs
+# html documentation
+if get_option('doc').enabled()
   message('--- doc dependencies ---')
   doxygen = find_program('doxygen')
   sphinx_build = find_program('sphinx-build-3', required: false)
@@ -46,38 +46,15 @@ if build_doc  # doxygen + html docs
   endif
   message('------------------------')
 
-  # create doxygen in source dir
-  doc_doxyxml = custom_target(
-    'doxyxml doc',
-    command: [
-      '../scripts/doc-doxyxml.sh',
-      meson.current_source_dir(),
-    ],
-    output: 'doxygen',
-    build_always_stale: true,
-    build_by_default: true,
-  )
-
-  # create html docs in build dir
-  doc = custom_target(
-    'html doc',
-    command: [
-      sphinx_build,
-      '-W',
-      '-b', 'html',
-      '-d', '.doctrees',
-      meson.current_source_dir(),
-      '@OUTPUT@',
-    ],
-    output: 'html',
-    build_always_stale: true,
-    build_by_default: true,
-    depends: doc_doxyxml,
-  )
-
   # install html docs
   install_subdir(
-    join_paths(meson.current_build_dir(), 'html'),
+    join_paths(meson.current_source_dir(), 'html'),
     install_dir: doc_dir,
   )
 endif
+
+make_doc = find_program('../scripts/make-doc.sh')
+run_target(
+  'doc',
+  command: make_doc,
+)

diff --git a/meson.build b/meson.build
index 439f3bf734b15c04a6120a6647eefe427d4341f9..20994fbed41f39734068cb62b817cb65f08e4ac3 100644 (file)
--- a/meson.build
+++ b/meson.build
@@ -182,9 +182,8 @@ install_data(
 s_managed_ta = managed_ta ? 'enabled' : 'disabled'
 s_systemd_socket = libsystemd.found() ? 'enabled' : 'disabled'
 s_build_client = build_client ? 'enabled' : 'disabled'
-s_build_doc = build_doc ? 'enabled' : 'disabled'
-s_build_postinstall_tests = build_postinstall_tests ? 'enabled' : 'disabled'
 s_build_unit_tests = build_unit_tests ? 'enabled' : 'disabled'
+s_build_postinstall_tests = build_postinstall_tests ? 'enabled' : 'disabled'
 s_install_kresd_conf = install_kresd_conf ? 'enabled' : 'disabled'
 message('''
 
@@ -208,7 +207,6 @@ message('''
 
   optional components
     client:             @0@'''.format(s_build_client) + '''
-    doc:                @0@'''.format(s_build_doc) + '''
     unit_tests:         @0@'''.format(s_build_unit_tests) + '''
     postinstall_tests:  @0@'''.format(s_build_postinstall_tests) + '''
 

diff --git a/meson_options.txt b/meson_options.txt
index f5fa093bf7e1c8c73a645dc05d316af758745fac..bd15eef51b36f64b3cf961953394f143e00c2c7d 100644 (file)
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -81,7 +81,7 @@ option(
   'doc',
   type: 'feature',
   value: 'disabled',
-  description: 'build html documentation',
+  description: 'html documentation dependencies and installation',
 )
 
 option(

diff --git a/scripts/doc-doxyxml.sh b/scripts/doc-doxyxml.sh
deleted file mode 100755 (executable)
index 2975a60..0000000
--- a/scripts/doc-doxyxml.sh
+++ /dev/null
@@ -1,5 +0,0 @@
-#!/bin/bash
-set -o errexit -o nounset
-
-cd $1
-doxygen

diff --git a/scripts/make-doc.sh b/scripts/make-doc.sh
new file mode 100755 (executable)
index 0000000..58e5b92
--- /dev/null
+++ b/scripts/make-doc.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+cd "$(dirname ${0})/.."
+
+pushd doc
+doxygen
+popd
+
+SPHINX=$(command -v sphinx-build-3)
+if [ $? -ne 0 ]; then
+    SPHINX=$(command -v sphinx-build)
+fi
+
+set -o errexit -o nounset
+
+${SPHINX} -W -b html -d doc/.doctrees doc doc/html