diff options
| -rw-r--r-- | doc/conf.py | 1 | ||||
| -rw-r--r-- | doc/meson.build | 5 | ||||
| -rw-r--r-- | doc/requirements.txt | 4 | ||||
| -rw-r--r-- | manager/poetry.lock | 206 | ||||
| -rw-r--r-- | manager/pyproject.toml | 4 | ||||
| -rwxr-xr-x | manager/scripts/docs | 10 | ||||
| -rwxr-xr-x | scripts/make-doc.sh | 6 |
7 files changed, 216 insertions, 20 deletions
diff --git a/doc/conf.py b/doc/conf.py index 8f9c9ab9..17640d31 100644 --- 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 94c93cfa..b374571d 100644 --- 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 32d347be..3fc4d399 100644 --- 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 a4ad595e..3055a0c5 100644 --- a/manager/poetry.lock +++ b/manager/poetry.lock @@ -285,6 +285,22 @@ 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" description = "A simple, correct Python build frontend" @@ -703,6 +719,26 @@ test = ["pretend", "pytest (>=6.2.0)", "pytest-benchmark", "pytest-cov", "pytest 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" description = "An implementation of the Debug Adapter Protocol for Python" @@ -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]] @@ -1000,6 +1036,17 @@ 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" description = "Internationalized Domain Names in Applications (IDNA)" @@ -1159,6 +1206,30 @@ MarkupSafe = ">=2.0" 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" description = "An implementation of JSON Schema validation for Python" @@ -1266,6 +1337,23 @@ files = [ ] [[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" description = "Safely add untrusted strings to HTML/XML markup." @@ -1326,6 +1414,42 @@ files = [ ] [[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" description = "McCabe checker, plugin for flake8" @@ -2350,6 +2474,47 @@ lint = ["docutils-stubs", "flake8 (>=3.5.0)", "flake8-bugbear", "flake8-comprehe 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" description = "sphinxcontrib-applehelp is a sphinx extension which outputs Apple help books" @@ -2398,6 +2563,21 @@ 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" description = "A sphinx extension which renders display math in HTML via JavaScript" @@ -2614,6 +2794,22 @@ files = [ ] [[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" description = "HTTP library with thread-safe connection pooling, file post, and more." @@ -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 3c7ff7ff..d7465ad3 100644 --- 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 index 00000000..10c83d8f --- /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 c1ad6b5e..37078a08 100755 --- 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 |