docs: generate documentation from poetry

diff --git a/doc/conf.py b/doc/conf.py
index 8f9c9ab98d81c3ce425da2b58b8d251f080935e3..17640d31dac83309c16f8f80e9baa34dcab4b927 100644 (file)
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -18,7 +18,6 @@ extensions = [
     'sphinx.ext.viewcode',
     'sphinx_tabs.tabs',
     'breathe',
-    'sphinx_mdinclude',
 ]
 
 # Breathe configuration

diff --git a/doc/meson.build b/doc/meson.build
index 94c93cfa419fdd7caf7a87ce06ac9b55029788ba..b374571d10d5cfdeed3efca8935afaf50779def3 100644 (file)
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -57,11 +57,6 @@ if get_option('doc') == 'enabled'
     error('missing doc dependency: python python-sphinx-tabs')
   endif
 
-  jsonschema2md = find_program('jsonschema2md')
-  if not jsonschema2md.found()
-    error('missing doc dependency: python jsonschema2md')
-  endif
-
   jsonschemaforhumans = run_command(python, '-c', 'import json_schema_for_humans', check: false)
   if jsonschemaforhumans.returncode() != 0
     error('missing doc dependency: python json-schema-for-humans')

diff --git a/doc/requirements.txt b/doc/requirements.txt
index 32d347be772cc880cb10dc8083ac5f527bfca9d9..3fc4d399dd24f1f2de3bb67e05d34ac149cb18b6 100644 (file)
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,6 +1,4 @@
 Sphinx>=3.0.0
 sphinx-tabs
 breathe
-jsonschema2md
-json-schema-for-humans
-sphinx_mdinclude
\ No newline at end of file
+json-schema-for-humans
\ No newline at end of file

diff --git a/manager/poetry.lock b/manager/poetry.lock
index a4ad595eb0361054a56573e993dd11bf987d90a8..3055a0c5f36e0f7eaaad4f727749994c98b24466 100644 (file)
--- a/manager/poetry.lock
+++ b/manager/poetry.lock
@@ -284,6 +284,22 @@ d = ["aiohttp (>=3.7.4)"]
 jupyter = ["ipython (>=7.8.0)", "tokenize-rt (>=3.2.0)"]
 uvloop = ["uvloop (>=0.15.2)"]
 
+[[package]]
+name = "breathe"
+version = "4.35.0"
+description = "Sphinx Doxygen renderer"
+category = "dev"
+optional = false
+python-versions = "*"
+files = [
+    {file = "breathe-4.35.0-py3-none-any.whl", hash = "sha256:52c581f42ca4310737f9e435e3851c3d1f15446205a85fbc272f1f97ed74f5be"},
+    {file = "breathe-4.35.0.tar.gz", hash = "sha256:5165541c3c67b6c7adde8b3ecfe895c6f7844783c4076b6d8d287e4f33d62386"},
+]
+
+[package.dependencies]
+docutils = ">=0.12"
+Sphinx = ">=4.0,<5.0.0 || >5.0.0"
+
 [[package]]
 name = "build"
 version = "0.10.0"
@@ -702,6 +718,26 @@ ssh = ["bcrypt (>=3.1.5)"]
 test = ["pretend", "pytest (>=6.2.0)", "pytest-benchmark", "pytest-cov", "pytest-xdist"]
 test-randomorder = ["pytest-randomly"]
 
+[[package]]
+name = "dataclasses-json"
+version = "0.5.9"
+description = "Easily serialize dataclasses to and from JSON"
+category = "dev"
+optional = false
+python-versions = ">=3.6"
+files = [
+    {file = "dataclasses-json-0.5.9.tar.gz", hash = "sha256:e9ac87b73edc0141aafbce02b44e93553c3123ad574958f0fe52a534b6707e8e"},
+    {file = "dataclasses_json-0.5.9-py3-none-any.whl", hash = "sha256:1280542631df1c375b7bc92e5b86d39e06c44760d7e3571a537b3b8acabf2f0c"},
+]
+
+[package.dependencies]
+marshmallow = ">=3.3.0,<4.0.0"
+marshmallow-enum = ">=1.5.1,<2.0.0"
+typing-inspect = ">=0.4.0"
+
+[package.extras]
+dev = ["flake8", "hypothesis", "ipython", "mypy (>=0.710)", "portray", "pytest (>=7.2.0)", "setuptools", "simplejson", "twine", "types-dataclasses", "wheel"]
+
 [[package]]
 name = "debugpy"
 version = "1.6.7"
@@ -759,14 +795,14 @@ files = [
 
 [[package]]
 name = "docutils"
-version = "0.19"
+version = "0.18.1"
 description = "Docutils -- Python Documentation Utilities"
 category = "dev"
 optional = false
-python-versions = ">=3.7"
+python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
 files = [
-    {file = "docutils-0.19-py3-none-any.whl", hash = "sha256:5e1de4d849fee02c63b040a4a3fd567f4ab104defd8a5511fbbc24a8a017efbc"},
-    {file = "docutils-0.19.tar.gz", hash = "sha256:33995a6753c30b7f577febfc2c50411fec6aac7f7ffeb7c4cfe5991072dcf9e6"},
+    {file = "docutils-0.18.1-py2.py3-none-any.whl", hash = "sha256:23010f129180089fbcd3bc08cfefccb3b890b0050e1ca00c867036e9d161b98c"},
+    {file = "docutils-0.18.1.tar.gz", hash = "sha256:679987caf361a7539d76e584cbeddc311e3aee937877c87346f31debc63e9d06"},
 ]
 
 [[package]]
@@ -999,6 +1035,17 @@ chardet = ["chardet (>=2.2)"]
 genshi = ["genshi"]
 lxml = ["lxml"]
 
+[[package]]
+name = "htmlmin"
+version = "0.1.12"
+description = "An HTML Minifier"
+category = "dev"
+optional = false
+python-versions = "*"
+files = [
+    {file = "htmlmin-0.1.12.tar.gz", hash = "sha256:50c1ef4630374a5d723900096a961cff426dff46b48f34d194a81bbe14eca178"},
+]
+
 [[package]]
 name = "idna"
 version = "3.4"
@@ -1158,6 +1205,30 @@ MarkupSafe = ">=2.0"
 [package.extras]
 i18n = ["Babel (>=2.7)"]
 
+[[package]]
+name = "json-schema-for-humans"
+version = "0.45.1"
+description = "Generate static HTML documentation from JSON schemas"
+category = "dev"
+optional = false
+python-versions = ">=3.7,<4.0"
+files = [
+    {file = "json_schema_for_humans-0.45.1-py3-none-any.whl", hash = "sha256:369aacf0a69925e24e6c43bf7145927d7f9668b508f87f773b38d1f9799516e1"},
+    {file = "json_schema_for_humans-0.45.1.tar.gz", hash = "sha256:372fc45e2e01a33cd58a36ffecb593250e591443871a41ca25b9542f1e3615b2"},
+]
+
+[package.dependencies]
+click = ">=8.0.1,<9.0.0"
+dataclasses-json = ">=0.5.6,<0.6.0"
+htmlmin = ">=0.1.12,<0.2.0"
+Jinja2 = ">3"
+markdown2 = ">=2.4.1,<3.0.0"
+MarkupSafe = ">=2.0,<3.0"
+Pygments = ">=2.10.0,<3.0.0"
+pytz = "*"
+PyYAML = ">=5.4.1,<7"
+requests = ">=2.31.0,<3.0.0"
+
 [[package]]
 name = "jsonschema"
 version = "4.17.3"
@@ -1265,6 +1336,23 @@ files = [
     {file = "lockfile-0.12.2.tar.gz", hash = "sha256:6aed02de03cba24efabcd600b30540140634fc06cfa603822d508d5361e9f799"},
 ]
 
+[[package]]
+name = "markdown2"
+version = "2.4.9"
+description = "A fast and complete Python implementation of Markdown"
+category = "dev"
+optional = false
+python-versions = ">=3.5, <4"
+files = [
+    {file = "markdown2-2.4.9-py2.py3-none-any.whl", hash = "sha256:58e1789543f47cdd4197760b04771671411f07699f958ad40a4b56c55ba3e668"},
+    {file = "markdown2-2.4.9.tar.gz", hash = "sha256:7a1742dade7ec29b90f5c1d5a820eb977eee597e314c428e6b0aa7929417cd1b"},
+]
+
+[package.extras]
+all = ["pygments (>=2.7.3)", "wavedrom"]
+code-syntax-highlighting = ["pygments (>=2.7.3)"]
+wavedrom = ["wavedrom"]
+
 [[package]]
 name = "markupsafe"
 version = "2.1.3"
@@ -1325,6 +1413,42 @@ files = [
     {file = "MarkupSafe-2.1.3.tar.gz", hash = "sha256:af598ed32d6ae86f1b747b82783958b1a4ab8f617b06fe68795c7f026abbdcad"},
 ]
 
+[[package]]
+name = "marshmallow"
+version = "3.19.0"
+description = "A lightweight library for converting complex datatypes to and from native Python datatypes."
+category = "dev"
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "marshmallow-3.19.0-py3-none-any.whl", hash = "sha256:93f0958568da045b0021ec6aeb7ac37c81bfcccbb9a0e7ed8559885070b3a19b"},
+    {file = "marshmallow-3.19.0.tar.gz", hash = "sha256:90032c0fd650ce94b6ec6dc8dfeb0e3ff50c144586462c389b81a07205bedb78"},
+]
+
+[package.dependencies]
+packaging = ">=17.0"
+
+[package.extras]
+dev = ["flake8 (==5.0.4)", "flake8-bugbear (==22.10.25)", "mypy (==0.990)", "pre-commit (>=2.4,<3.0)", "pytest", "pytz", "simplejson", "tox"]
+docs = ["alabaster (==0.7.12)", "autodocsumm (==0.2.9)", "sphinx (==5.3.0)", "sphinx-issues (==3.0.1)", "sphinx-version-warning (==1.1.2)"]
+lint = ["flake8 (==5.0.4)", "flake8-bugbear (==22.10.25)", "mypy (==0.990)", "pre-commit (>=2.4,<3.0)"]
+tests = ["pytest", "pytz", "simplejson"]
+
+[[package]]
+name = "marshmallow-enum"
+version = "1.5.1"
+description = "Enum field for Marshmallow"
+category = "dev"
+optional = false
+python-versions = "*"
+files = [
+    {file = "marshmallow-enum-1.5.1.tar.gz", hash = "sha256:38e697e11f45a8e64b4a1e664000897c659b60aa57bfa18d44e226a9920b6e58"},
+    {file = "marshmallow_enum-1.5.1-py2.py3-none-any.whl", hash = "sha256:57161ab3dbfde4f57adeb12090f39592e992b9c86d206d02f6bd03ebec60f072"},
+]
+
+[package.dependencies]
+marshmallow = ">=2.0.0"
+
 [[package]]
 name = "mccabe"
 version = "0.7.0"
@@ -2349,6 +2473,47 @@ docs = ["sphinxcontrib-websupport"]
 lint = ["docutils-stubs", "flake8 (>=3.5.0)", "flake8-bugbear", "flake8-comprehensions", "flake8-simplify", "isort", "mypy (>=0.981)", "sphinx-lint", "types-requests", "types-typed-ast"]
 test = ["cython", "html5lib", "pytest (>=4.6)", "typed_ast"]
 
+[[package]]
+name = "sphinx-rtd-theme"
+version = "1.2.2"
+description = "Read the Docs theme for Sphinx"
+category = "dev"
+optional = false
+python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7"
+files = [
+    {file = "sphinx_rtd_theme-1.2.2-py2.py3-none-any.whl", hash = "sha256:6a7e7d8af34eb8fc57d52a09c6b6b9c46ff44aea5951bc831eeb9245378f3689"},
+    {file = "sphinx_rtd_theme-1.2.2.tar.gz", hash = "sha256:01c5c5a72e2d025bd23d1f06c59a4831b06e6ce6c01fdd5ebfe9986c0a880fc7"},
+]
+
+[package.dependencies]
+docutils = "<0.19"
+sphinx = ">=1.6,<7"
+sphinxcontrib-jquery = ">=4,<5"
+
+[package.extras]
+dev = ["bump2version", "sphinxcontrib-httpdomain", "transifex-client", "wheel"]
+
+[[package]]
+name = "sphinx-tabs"
+version = "3.4.1"
+description = "Tabbed views for Sphinx"
+category = "dev"
+optional = false
+python-versions = "~=3.7"
+files = [
+    {file = "sphinx-tabs-3.4.1.tar.gz", hash = "sha256:d2a09f9e8316e400d57503f6df1c78005fdde220e5af589cc79d493159e1b832"},
+    {file = "sphinx_tabs-3.4.1-py3-none-any.whl", hash = "sha256:7cea8942aeccc5d01a995789c01804b787334b55927f29b36ba16ed1e7cb27c6"},
+]
+
+[package.dependencies]
+docutils = ">=0.18.0,<0.19.0"
+pygments = "*"
+sphinx = "*"
+
+[package.extras]
+code-style = ["pre-commit (==2.13.0)"]
+testing = ["bs4", "coverage", "pygments", "pytest (>=7.1,<8)", "pytest-cov", "pytest-regressions", "rinohtype", "sphinx-testing"]
+
 [[package]]
 name = "sphinxcontrib-applehelp"
 version = "1.0.2"
@@ -2397,6 +2562,21 @@ files = [
 lint = ["docutils-stubs", "flake8", "mypy"]
 test = ["html5lib", "pytest"]
 
+[[package]]
+name = "sphinxcontrib-jquery"
+version = "4.1"
+description = "Extension to include jQuery on newer Sphinx releases"
+category = "dev"
+optional = false
+python-versions = ">=2.7"
+files = [
+    {file = "sphinxcontrib-jquery-4.1.tar.gz", hash = "sha256:1620739f04e36a2c779f1a131a2dfd49b2fd07351bf1968ced074365933abc7a"},
+    {file = "sphinxcontrib_jquery-4.1-py2.py3-none-any.whl", hash = "sha256:f936030d7d0147dd026a4f2b5a57343d233f1fc7b363f68b3d4f1cb0993878ae"},
+]
+
+[package.dependencies]
+Sphinx = ">=1.8"
+
 [[package]]
 name = "sphinxcontrib-jsmath"
 version = "1.0.1"
@@ -2613,6 +2793,22 @@ files = [
     {file = "typing_extensions-4.6.3.tar.gz", hash = "sha256:d91d5919357fe7f681a9f2b5b4cb2a5f1ef0a1e9f59c4d8ff0d3491e05c0ffd5"},
 ]
 
+[[package]]
+name = "typing-inspect"
+version = "0.9.0"
+description = "Runtime inspection utilities for typing module."
+category = "dev"
+optional = false
+python-versions = "*"
+files = [
+    {file = "typing_inspect-0.9.0-py3-none-any.whl", hash = "sha256:9ee6fc59062311ef8547596ab6b955e1b8aa46242d854bfc78f4f6b0eff35f9f"},
+    {file = "typing_inspect-0.9.0.tar.gz", hash = "sha256:b23fc42ff6f6ef6954e4852c1fb512cdd18dbea03134f91f856a95ccc9461f78"},
+]
+
+[package.dependencies]
+mypy-extensions = ">=0.3.0"
+typing-extensions = ">=3.7.4"
+
 [[package]]
 name = "urllib3"
 version = "1.26.16"
@@ -2942,4 +3138,4 @@ testing = ["big-O", "flake8 (<5)", "jaraco.functools", "jaraco.itertools", "more
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.7"
-content-hash = "16ce34509fd2c4b4bedee9c8fc289f077bbe3057e95e7a2736ce71d994499444"
+content-hash = "358f1b25ba492986c13b3602b6ebb6a3be3b5b0fafb660c06247cf6b8ac3946a"

diff --git a/manager/pyproject.toml b/manager/pyproject.toml
index 3c7ff7ff18a73ee7bfbfec4854e4c1b4c3aba51d..d7465ad33f0b49c1216189353f4745db4837a5ac 100644 (file)
--- a/manager/pyproject.toml
+++ b/manager/pyproject.toml
@@ -46,6 +46,10 @@ flake8 = {version = "*", python = "^3.8.1"}
 
 [tool.poetry.group.docs.dependencies]
 sphinx = "^5.3.0"
+sphinx-tabs = "^3.4.1"
+sphinx-rtd-theme = "^1.2.2"
+breathe = "^4.35.0"
+json-schema-for-humans = "^0.45.1"
 
 [tool.poetry.scripts]
 kresctl = 'knot_resolver_manager.cli.main:main'

diff --git a/manager/scripts/docs b/manager/scripts/docs
new file mode 100755 (executable)
index 0000000..10c83d8
--- /dev/null
+++ b/manager/scripts/docs
@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# ensure consistent behaviour
+src_dir="$(dirname "$(realpath "$0")")"
+source $src_dir/_env.sh
+cd ..
+
+echo Building documentation for Knot Resolver
+meson build_doc -Ddoc=enabled
+ninja -C build_doc doc

diff --git a/scripts/make-doc.sh b/scripts/make-doc.sh
index c1ad6b5ea17f997386de07d7626767998b1de6ae..37078a082587ffa79e450bb2144ae8c7667a7dad 100755 (executable)
--- a/scripts/make-doc.sh
+++ b/scripts/make-doc.sh
@@ -8,14 +8,8 @@ pushd manager
 mkdir -p ../doc/_static/
 python3 -m knot_resolver_manager.cli schema > ../doc/_static/config.schema.json
 generate-schema-doc --config expand_buttons=true ../doc/_static/config.schema.json ../doc/_static/schema_doc.html
-
-# generate readable version of the JSON schema
-# we could replace jsonschema2md with the following at some point in the future:
-#generate-schema-doc --config template_name=md --config show_toc=false ../doc/_static/config.schema.json ../doc/_static/schema_doc.md
-jsonschema2md ../doc/_static/config.schema.json /dev/stdout | sed 's/^#/###/' > ../doc/config-schema-body.md
 popd
 
-
 pushd doc
 doxygen
 popd