diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | .gitlab-ci.yml | 20 | ||||
| -rw-r--r-- | distro/arch/PKGBUILD | 3 | ||||
| -rwxr-xr-x | distro/deb/rules | 1 | ||||
| -rw-r--r-- | distro/rpm/knot-resolver.spec | 3 | ||||
| -rw-r--r-- | doc/build.rst | 16 | ||||
| -rw-r--r-- | doc/meson.build | 41 | ||||
| -rw-r--r-- | meson.build | 4 | ||||
| -rw-r--r-- | meson_options.txt | 2 | ||||
| -rwxr-xr-x | scripts/doc-doxyxml.sh | 5 | ||||
| -rwxr-xr-x | scripts/make-doc.sh | 15 |
11 files changed, 58 insertions, 53 deletions
@@ -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 ec00ea41..16f7124b 100644 --- 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 959dd070..bb0cb497 100644 --- 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 43d36da3..f0a3d7e2 100755 --- 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 49d2b71f..c2b76e38 100644 --- 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 5f9b22e3..59ffdf59 100644 --- 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 c39a71ca..4e72499c 100644 --- 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 439f3bf7..20994fbe 100644 --- 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 f5fa093b..bd15eef5 100644 --- 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 index 2975a600..00000000 --- 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 index 00000000..58e5b925 --- /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 |