From b4c863ff065b8804192cdf37fc69caa226441ca0 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ale=C5=A1=20Mr=C3=A1zek?= Date: Wed, 19 Jul 2023 16:18:23 +0200 Subject: [PATCH] docs: generate documentation from poetry --- doc/conf.py | 1 - doc/meson.build | 5 - doc/requirements.txt | 4 +- manager/poetry.lock | 206 ++++++++++++++++++++++++++++++++++++++++- manager/pyproject.toml | 4 + manager/scripts/docs | 10 ++ scripts/make-doc.sh | 6 -- 7 files changed, 216 insertions(+), 20 deletions(-) create mode 100755 manager/scripts/docs diff --git a/doc/conf.py b/doc/conf.py index 8f9c9ab98..17640d31d 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 94c93cfa4..b374571d1 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 32d347be7..3fc4d399d 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 a4ad595eb..3055a0c5f 100644 --- 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 3c7ff7ff1..d7465ad33 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 000000000..10c83d8fc --- /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 c1ad6b5ea..37078a082 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 -- 2.47.2