[#2969] revised the quickstart page

- added link to the cloudsmith tarball page
- added |cloudsmith_repo| substitution
- added sphinx-tabs extension
- changed yum to dnf because with the deprecation of CentOS 7, all
  remaining supported rpm distributions have dnf by default.
- changed `/path/to/your/kea6/config/file.json` to the configuration
  file installed by default `/etc/kea/kea-dhcp6.conf` for easier startup
- regenerated doc/sphinx/src/requirements.txt mainly to include
  sphinx-tabs
- added sphinx-tabs to hammer.py

diff --git a/doc/sphinx/arm/quickstart.rst b/doc/sphinx/arm/quickstart.rst
index cf0360e28e70d775693bec0cff1d87df5b3ebb6a..97c42068473a944dded8b13be47e79864fc116b8 100644 (file)
--- a/doc/sphinx/arm/quickstart.rst
+++ b/doc/sphinx/arm/quickstart.rst
@@ -16,9 +16,10 @@ Quick Start Guide Using tarball
 1.  Install required runtime and build dependencies. See
     :ref:`build-requirements` for details.
 
-2.  Download the Kea source tarball from the `ISC.org downloads
-    page <https://www.isc.org/download/>`__ or the `ISC downloads site
-    <https://downloads.isc.org/isc/kea/>`__.
+2.  Download the Kea source tarball from
+    `the ISC.org downloads page <https://www.isc.org/download/>`__ or
+    `the ISC downloads site <https://downloads.isc.org/isc/kea/>`__ or
+    `the ISC Cloudsmith page <https://cloudsmith.io/~isc/packages/?q=format%3Araw>`__.
 
 3.  Extract the tarball. For example:
 
@@ -55,95 +56,156 @@ ISC provides native Alpine, deb, and RPM packages, which make Kea installation
 much easier. Unless specific compilation options are desired, it is usually
 easier to install Kea using native packages.
 
-1. Go to `Kea on cloudsmith.io <https://cloudsmith.io/~isc/repos/>`__,
-   choose the Kea version, and enter the repository.
+1. Go to `Kea on cloudsmith.io <https://cloudsmith.io/~isc/repos/>`__.
 
-2. Use ``Set Me Up`` and follow instructions to add the repository
-   to the local system.
+2. Choose the Cloudsmith repository e.g. |cloudsmith_repo| for Kea |version|.
+
+3. Click on the arrow besides the ``Set Me Up`` button and select your OS flavor
+   out of: ``Alpine``, ``Debian``, ``RedHat``.
+
+4. Follow the instructions written there.
 
 .. note::
-  For example, the Debian setup instructions for Kea 2.3 can be found here:
-  https://cloudsmith.io/~isc/repos/kea-2-3/setup/#formats-deb
+  For example, the Debian setup instructions for Kea 2.4 can be found here:
+  https://cloudsmith.io/~isc/repos/kea-2-4/setup/#formats-deb
 
   The dropdown near the top of the page offers instructions for
   other operating systems.
 
-3. Update system repositories. For example, on Debian/Ubuntu:
+5. Kea is split into various packages. The entire list is available on the
+   Cloudsmith repository page under ``Packages``, or it can be retrieved
+   using ``apk``/``apt``/``dnf``.
 
-    .. code-block:: console
+.. tabs::
 
-        $ sudo apt update
+    .. tab:: Debian/Ubuntu
 
-   On CentOS/Fedora:
+        .. code-block:: console
 
-    .. code-block:: console
+            $ apt search isc-kea
 
-        $ sudo yum update
+        .. note::
+            ``isc-kea-dhcp4-server`` and ``isc-kea-dhcp6-server`` are empty
+            transitional packages. The working server packages are
+            ``isc-kea-dhcp4`` and ``isc-kea-dhcp6``.
 
-   On Alpine:
+    .. tab:: Fedora/RedHat
 
-    .. code-block:: console
+        .. code-block:: console
 
-        # apk update
+            $ dnf search 'isc-kea*'
 
-4. Kea is split into various packages. The entire list is available on
-   `cloudsmith.io <https://cloudsmith.io/~isc/repos/>`__ or using apt/yum/dnf.
-   For example, on Debian/Ubuntu:
+    .. tab:: Alpine
 
-    .. code-block:: console
+        .. code-block:: console
 
-        $ apt search isc-kea
+            $ apk search isc-kea
 
-   On CentOS/Fedora:
+6. Install the metapackage containing all the tools, libraries, servers,
+   documentation, and open source hooks:
 
-    .. code-block:: console
+.. tabs::
 
-        $ yum search isc-kea
+    .. tab:: Debian/Ubuntu
 
-   On Alpine:
+        .. code-block:: console
 
-    .. code-block:: console
+            $ sudo apt install isc-kea
 
-        $ apk search isc-kea
+    .. tab:: Fedora/RedHat
 
-5. Install the metapackage containing all of the tools, services, and open
-   source hooks:
+        .. code-block:: console
 
-    .. code-block:: console
+            $ sudo dnf install isc-kea
 
-        $ sudo apt install isc-kea
+    .. tab:: Alpine
 
-   or specific packages:
+        .. code-block:: console
 
-    .. code-block:: console
+            # apk add isc-kea
 
-        $ sudo apt install isc-kea-dhcp6
+or specific packages:
 
-   or every single Kea-related package, including development headers, debug
-   symbols, and premium hooks (if available):
+.. tabs::
 
-    .. code-block:: console
+    .. tab:: Debian/Ubuntu
 
-        $ sudo apt install isc-kea*
+        .. code-block:: console
 
-   or all packages with a specified version number:
+            $ sudo apt install isc-kea-dhcp6
 
-    .. code-block:: console
+    .. tab:: Fedora/RedHat
 
-        $ sudo apt install isc-kea*=2.4.0-isc20230531000000
+        .. code-block:: console
 
-.. note::
-  Not all package managers support installing packages with a glob (``*``),
-  please refer to the specific package manager's manual before attempting this.
+            $ sudo dnf install isc-kea-dhcp6
+
+    .. tab:: Alpine
+
+        .. code-block:: console
+
+            $ apk add isc-kea-dhcp6
+
+or every single Kea-related package, including development headers, debug
+symbols, and premium hooks (if available):
+
+.. tabs::
+
+    .. tab:: Debian/Ubuntu
+
+        .. code-block:: console
+
+            $ sudo apt install 'isc-kea*'
+
+    .. tab:: Fedora/RedHat
 
-  - On CentOS/Fedora systems, replace ``apt install`` with ``yum install``.
-  - On Alpine systems, replace ``apt install`` with ``apk add``.
+        .. code-block:: console
 
-6. All installed packages should be now available directly; for example:
+            $ sudo dnf install 'isc-kea*'
+
+    .. tab:: Alpine
+
+        Installing packages via globbing (``*``) is not available for Alpine,
+        but it can be simulated with the following command:
+
+        .. code-block:: console
+
+            # apk search isc-kea | sed 's/-[0-9].*//g' | xargs apk add
+
+or all packages with a specified version number:
+
+.. tabs::
+
+    .. tab:: Debian/Ubuntu
+
+        .. code-block:: console
+
+            $ sudo apt install 'isc-kea*=2.4.0-isc20230921141113'
+
+    .. tab:: Fedora/RedHat
+
+        .. code-block:: console
+
+            $ sudo dnf install 'isc-kea*2.4.0-isc20230921141113*'
+
+    .. tab:: Alpine
+
+        .. code-block:: console
+
+        Installing packages via globbing (``*``) is not available for Alpine,
+        but it can be simulated with the following command:
+
+        .. code-block:: console
+
+            # apk search isc-kea | sed 's/-[0-9].*//g' | grep r20230921141113 | xargs apk add
+
+8. All installed packages should be now available directly.
+
+    You can start a server up manually:
 
     .. code-block:: console
 
-        # kea-dhcp6 -c /path/to/your/kea6/config/file.json
+        # kea-dhcp6 -c /etc/kea/kea-dhcp6.conf
 
    or using systemd:
 
@@ -161,16 +223,17 @@ easier to install Kea using native packages.
   :iscman:`keactrl` is not available in packages, as similar functionality is provided
   by the native systemctl scripts.
 
-7. On CentOS, Fedora, and Alpine, the service must be enabled at boot
-   time if desired; this is done automatically at package
-   installation time on Debian and Ubuntu systems. For example, with systemd
-   on CentOS/Fedora:
+9. On Debian/Ubuntu systems, the service is enabled at boot time automatically
+   when the package is installed. On Fedora/RHEL and Alpine, the service is not
+   enabled automatically, so, if desired, it must be enabled manually.
+
+    With systemd on Fedora/RedHat:
 
     .. code-block:: console
 
         # systemctl enable kea-dhcp6
 
-   With OpenRC on Alpine:
+    With OpenRC on Alpine:
 
     .. code-block:: console
 
@@ -180,6 +243,7 @@ easier to install Kea using native packages.
 
 Quick Start Guide for DHCPv4 and DHCPv6 Services
 ================================================
+
 1.  Edit the Kea configuration files, which by default are installed in
     the ``[kea-install-dir]/etc/kea/`` directory. These are:
     ``kea-dhcp4.conf``, ``kea-dhcp6.conf``, ``kea-dhcp-ddns.conf`` and

diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
index 79ce3ba19c7745b179b675d7e3f57076f37b08e3..af64d08be1bef71ed07fddb757f5f387a1a4c96f 100644 (file)
--- a/doc/sphinx/conf.py
+++ b/doc/sphinx/conf.py
@@ -45,6 +45,7 @@ with open(config_ac_path) as f:
                     release = candidate_release
             break
 version = release
+dashed_version_series='-'.join(version.split('.')[0:2])
 
 # -- General configuration ---------------------------------------------------
 
@@ -58,6 +59,7 @@ version = release
 extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
+    'sphinx_tabs.tabs',
 ]
 
 # The suffix(es) of source filenames.
@@ -229,7 +231,13 @@ man_pages = [
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+# -- Substitutions -----------------------------------------------------------
 
+rst_prolog="""
+.. |cloudsmith_repo| replace:: kea-{dashed_version_series}
+""".format(dashed_version_series=dashed_version_series)
+
+# -- Functions ---------------------------------------------------------------
 
 # Do generation of api.rst and kea-messages.rst here in conf.py instead of Makefile.am
 # so they are available on ReadTheDocs as there makefiles are not used for building docs.

diff --git a/doc/sphinx/src/requirements.in b/doc/sphinx/src/requirements.in
index cbf1e3658e6aa8a22988927b510080a973450f52..fc5c91382ccbc515a5415140ca19ac3c5e06edfe 100644 (file)
--- a/doc/sphinx/src/requirements.in
+++ b/doc/sphinx/src/requirements.in
@@ -1,2 +1,3 @@
 sphinx
 sphinx-rtd-theme
+sphinx-tabs

diff --git a/doc/sphinx/src/requirements.txt b/doc/sphinx/src/requirements.txt
index 82820a4f44f18577d06a4b23332dfef0457a7334..214d62d1ceb41531b3ec90e7aabe936223feb10c 100644 (file)
--- a/doc/sphinx/src/requirements.txt
+++ b/doc/sphinx/src/requirements.txt
@@ -6,52 +6,63 @@
 #
 alabaster==0.7.13
     # via sphinx
-babel==2.12.1
+babel==2.13.0
     # via sphinx
-certifi==2023.5.7
+certifi==2023.7.22
     # via requests
-charset-normalizer==3.1.0
+charset-normalizer==3.3.0
     # via requests
 docutils==0.18.1
     # via
     #   sphinx
     #   sphinx-rtd-theme
+    #   sphinx-tabs
 idna==3.4
     # via requests
 imagesize==1.4.1
     # via sphinx
 jinja2==3.1.2
     # via sphinx
-markupsafe==2.1.2
+markupsafe==2.1.3
     # via jinja2
-packaging==23.1
-    # via sphinx
-pygments==2.15.1
+packaging==23.2
     # via sphinx
+pygments==2.16.1
+    # via
+    #   sphinx
+    #   sphinx-tabs
 requests==2.31.0
     # via sphinx
 snowballstemmer==2.2.0
     # via sphinx
-sphinx==6.2.1
+sphinx==7.2.6
     # via
     #   -r ./src/requirements.in
     #   sphinx-rtd-theme
+    #   sphinx-tabs
+    #   sphinxcontrib-applehelp
+    #   sphinxcontrib-devhelp
+    #   sphinxcontrib-htmlhelp
     #   sphinxcontrib-jquery
-sphinx-rtd-theme==1.2.1
+    #   sphinxcontrib-qthelp
+    #   sphinxcontrib-serializinghtml
+sphinx-rtd-theme==1.3.0
+    # via -r ./src/requirements.in
+sphinx-tabs==3.4.1
     # via -r ./src/requirements.in
-sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-applehelp==1.0.7
     # via sphinx
-sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-devhelp==1.0.5
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-htmlhelp==2.0.4
     # via sphinx
 sphinxcontrib-jquery==4.1
     # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-qthelp==1.0.6
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==1.1.9
     # via sphinx
-urllib3==2.0.2
+urllib3==2.0.6
     # via requests

diff --git a/hammer.py b/hammer.py
index affdfedd2a631f4374210a4c610a10da1e89c6bd..153806cd1e9e9fb3fb582c56ea4e75ec450e6099 100755 (executable)
--- a/hammer.py
+++ b/hammer.py
@@ -1721,7 +1721,7 @@ def prepare_system_local(features, check_times, ignore_errors_for):
         if 'docs' in features:
             execute('python3 -m venv ~/venv',
                     env=env, timeout=60, check_times=check_times)
-            execute('~/venv/bin/pip install sphinx sphinx-rtd-theme',
+            execute('~/venv/bin/pip install sphinx sphinx-rtd-theme sphinx-tabs',
                     env=env, timeout=120, check_times=check_times)
 
     # prepare rhel
@@ -1773,7 +1773,7 @@ def prepare_system_local(features, check_times, ignore_errors_for):
         if 'docs' in features:
             execute('python3 -m venv ~/venv',
                     env=env, timeout=60, check_times=check_times)
-            execute('~/venv/bin/pip install sphinx sphinx-rtd-theme',
+            execute('~/venv/bin/pip install sphinx sphinx-rtd-theme sphinx-tabs',
                     env=env, timeout=120, check_times=check_times)
 
     # prepare ubuntu
@@ -1790,7 +1790,8 @@ def prepare_system_local(features, check_times, ignore_errors_for):
                 packages.append('googletest')
 
         if 'docs' in features:
-            packages.extend(['python3-sphinx', 'python3-sphinx-rtd-theme', 'texlive', 'texlive-latex-extra'])
+            packages.extend(['python3-sphinx', 'python3-sphinx-rtd-theme', 'python3-sphinx-tabs',
+                             'texlive', 'texlive-latex-extra'])
             if revision == '22.04':
                 packages.extend(['tex-gyre'])
 
@@ -1849,7 +1850,8 @@ def prepare_system_local(features, check_times, ignore_errors_for):
             if revision == '8':
                 packages.extend(['virtualenv'])
             else:
-                packages.extend(['python3-sphinx', 'python3-sphinx-rtd-theme', 'texlive', 'texlive-latex-extra'])
+                packages.extend(['python3-sphinx', 'python3-sphinx-rtd-theme', 'python3-sphinx-tabs',
+                                 'texlive', 'texlive-latex-extra'])
                 if revision == '9':
                     packages.extend(['texlive-generic-extra'])
                 if revision == '12':
@@ -1893,7 +1895,7 @@ def prepare_system_local(features, check_times, ignore_errors_for):
             if revision == '8':
                 execute('python3 -m venv ~/venv',
                         env=env, timeout=60, check_times=check_times)
-                execute('~/venv/bin/pip install sphinx sphinx-rtd-theme',
+                execute('~/venv/bin/pip install sphinx sphinx-rtd-theme sphinx-tabs',
                         env=env, timeout=120, check_times=check_times)
 
     # prepare freebsd