diff --git a/.bumpversion.cfg b/.bumpversion.cfg index bdccf04..b961596 100644 --- a/.bumpversion.cfg +++ b/.bumpversion.cfg @@ -16,3 +16,7 @@ replace = "version": "{new_version}", [bumpversion:file:publiccode.yaml] search = softwareVersion: {current_version} replace = softwareVersion: {new_version} + +[bumpversion:file:src/openzaak/__init__.py] +search = __version__ = "{current_version}" +replace = __version__ = "{new_version}" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5036b9a..bed093c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -95,6 +95,18 @@ jobs: main-branch: 'master' python-version: '3.11' docker-image-name: ${{ needs.store-reusable-workflow-vars.outputs.image-name }} + run-docs: false + + dummy-job: + runs-on: ubuntu-latest + name: Dummy Job to Test Workflow + needs: + - open-api-ci + steps: + - name: Echo Dummy Test + run: echo "This is a dummy job to test the workflow execution." + + open-api-publish: uses: maykinmedia/open-api-workflows/.github/workflows/publish.yml@v1 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/check_sphinx.py b/docs/check_sphinx.py new file mode 100644 index 0000000..cc1003a --- /dev/null +++ b/docs/check_sphinx.py @@ -0,0 +1,17 @@ +import subprocess + + +def test_linkcheck(tmpdir): + doctrees = tmpdir.join("doctrees") + htmldir = tmpdir.join("html") + subprocess.check_call( + ["sphinx-build", "-W", "-blinkcheck", "-d", str(doctrees), ".", str(htmldir)], + ) + + +def test_build_docs(tmpdir): + doctrees = tmpdir.join("doctrees") + htmldir = tmpdir.join("html") + subprocess.check_call( + ["sphinx-build", "-W", "-bhtml", "-d", str(doctrees), ".", str(htmldir)], + ) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..8d2ad5a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,90 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- +import os +import sys + +sys.path.insert(0, os.path.abspath("../src")) + +import objecttypes # noqa isort:skip + +# from objects.setup import setup_env # noqa isort:skip + +# TODO: This needs to be enabled when we want to use autodoc to grab +# documentation from classes and functions. However, enabling django.setup() +# causes RTD to fail because GDAL is not present in the RTD environment. +# See: https://github.com/readthedocs/readthedocs-docker-images/issues/114#issuecomment-570566599 +# +# setup_env() +# django.setup() + +# -- Project information ----------------------------------------------------- + +project = "Objects and Objecttypes API" +copyright = "2020, Maykin Media" +author = objecttypes.__author__ + +# The full version, including alpha/beta/rc tags +release = objecttypes.__version__ + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.todo", + "sphinx_tabs.tabs", + "recommonmark", + # "sphinx_markdown_tables", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = "en" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +source_suffix = [".rst", ".md"] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_logo = "logo.png" +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] +html_css_files = [ + "theme_overrides.css", # override wide tables with word wrap +] + +todo_include_todos = True + +linkcheck_timeout = 10 +linkcheck_ignore = [ + r"https?://.*\.gemeente.nl", + r"http://localhost:\d+/", + r"https://.*sentry.*", + "https://github.com/maykinmedia/objects-api-performance", + "https://objects.municipality.nl/admin/", + "https://sparxsystems.com/products/ea/trial/request.html", # this raises 403 for crawlers probably? +] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..9d89971 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,2 @@ +Documentation +============= diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..2119f51 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/requirements/ci.txt b/requirements/ci.txt index 3ca4980..3e2b661 100644 --- a/requirements/ci.txt +++ b/requirements/ci.txt @@ -4,6 +4,8 @@ # # pip-compile --no-emit-index-url --output-file=requirements/ci.txt requirements/base.txt requirements/ci.in requirements/test-tools.in # +alabaster==1.0.0 + # via sphinx amqp==5.1.1 # via # -r requirements/base.txt @@ -33,6 +35,8 @@ attrs==23.1.0 # -r requirements/base.txt # glom # jsonschema +babel==2.16.0 + # via sphinx beautifulsoup4==4.12.2 # via webtest billiard==4.2.0 @@ -100,6 +104,8 @@ commonground-api-common==2.1.0 # via # -r requirements/base.txt # open-api-framework +commonmark==0.9.1 + # via recommonmark coreapi==2.3.3 # via # -r requirements/base.txt @@ -290,6 +296,12 @@ djangorestframework-inclusions==1.2.0 # via # -r requirements/base.txt # open-api-framework +docutils==0.21.2 + # via + # recommonmark + # sphinx + # sphinx-rtd-theme + # sphinx-tabs drf-nested-routers==0.94.1 # via # -r requirements/base.txt @@ -348,11 +360,15 @@ idna==3.7 # -r requirements/base.txt # requests # yarl +imagesize==1.4.1 + # via sphinx inflection==0.5.1 # via # -r requirements/base.txt # drf-spectacular # drf-yasg +iniconfig==2.0.0 + # via pytest iso-639==0.4.5 # via # -r requirements/base.txt @@ -371,6 +387,7 @@ jinja2==3.1.4 # via # -r requirements/base.txt # coreschema + # sphinx josepy==1.13.0 # via # -r requirements/base.txt @@ -427,6 +444,8 @@ packaging==23.1 # -r requirements/base.txt # black # drf-yasg + # pytest + # sphinx pathspec==0.12.1 # via black phonenumberslite==8.13.30 @@ -435,6 +454,8 @@ phonenumberslite==8.13.30 # django-two-factor-auth platformdirs==4.3.6 # via black +pluggy==1.5.0 + # via pytest prometheus-client==0.20.0 # via # -r requirements/base.txt @@ -469,6 +490,10 @@ pydantic-settings[yaml]==2.6.1 # pydantic-settings pyflakes==3.2.0 # via flake8 +pygments==2.18.0 + # via + # sphinx + # sphinx-tabs pyjwt==2.7.0 # via # -r requirements/base.txt @@ -485,6 +510,8 @@ pyrsistent==0.19.3 # via # -r requirements/base.txt # jsonschema +pytest==8.3.4 + # via -r requirements/test-tools.in python-dateutil==2.8.2 # via # -r requirements/base.txt @@ -518,6 +545,8 @@ qrcode==6.1 # via # -r requirements/base.txt # django-two-factor-auth +recommonmark==0.7.1 + # via -r requirements/test-tools.in redis==4.5.5 # via # -r requirements/base.txt @@ -534,6 +563,7 @@ requests==2.32.3 # open-api-framework # requests-mock # sharing-configs + # sphinx # zgw-consumers requests-mock==1.12.1 # via @@ -556,8 +586,35 @@ six==1.16.0 # orderedmultidict # python-dateutil # qrcode +snowballstemmer==2.2.0 + # via sphinx soupsieve==2.4.1 # via beautifulsoup4 +sphinx==8.1.3 + # via + # -r requirements/test-tools.in + # recommonmark + # sphinx-rtd-theme + # sphinx-tabs + # sphinxcontrib-jquery +sphinx-rtd-theme==3.0.2 + # via -r requirements/test-tools.in +sphinx-tabs==3.4.7 + # via -r requirements/test-tools.in +sphinxcontrib-applehelp==2.0.0 + # via sphinx +sphinxcontrib-devhelp==2.0.0 + # via sphinx +sphinxcontrib-htmlhelp==2.1.0 + # via sphinx +sphinxcontrib-jquery==4.1 + # via sphinx-rtd-theme +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==2.0.0 + # via sphinx +sphinxcontrib-serializinghtml==2.0.0 + # via sphinx sqlparse==0.5.0 # via # -r requirements/base.txt diff --git a/requirements/dev.in b/requirements/dev.in index ad0e948..4d1a098 100644 --- a/requirements/dev.in +++ b/requirements/dev.in @@ -5,7 +5,3 @@ bumpversion # Debug tooling django-debug-toolbar django-extensions - -# Documentation -sphinx -sphinx_rtd_theme diff --git a/requirements/dev.txt b/requirements/dev.txt index 7a4b1c3..67c0b88 100644 --- a/requirements/dev.txt +++ b/requirements/dev.txt @@ -109,6 +109,8 @@ commonground-api-common==2.1.0 # via # -r requirements/base.txt # open-api-framework +commonmark==0.9.1 + # via recommonmark coreapi==2.3.3 # via # -r requirements/base.txt @@ -303,8 +305,10 @@ djangorestframework-inclusions==1.2.0 # open-api-framework docutils==0.18.1 # via + # recommonmark # sphinx # sphinx-rtd-theme + # sphinx-tabs drf-nested-routers==0.94.1 # via # -r requirements/base.txt @@ -370,6 +374,8 @@ inflection==0.5.1 # -r requirements/base.txt # drf-spectacular # drf-yasg +iniconfig==2.0.0 + # via pytest iso-639==0.4.5 # via # -r requirements/base.txt @@ -446,6 +452,7 @@ packaging==23.1 # black # build # drf-yasg + # pytest # sphinx pathspec==0.11.1 # via black @@ -457,6 +464,8 @@ pip-tools==7.3.0 # via -r requirements/dev.in platformdirs==3.5.1 # via black +pluggy==1.5.0 + # via pytest prometheus-client==0.20.0 # via # -r requirements/base.txt @@ -492,7 +501,9 @@ pydantic-settings[yaml]==2.6.1 pyflakes==3.0.1 # via flake8 pygments==2.15.1 - # via sphinx + # via + # sphinx + # sphinx-tabs pyjwt==2.7.0 # via # -r requirements/base.txt @@ -511,6 +522,8 @@ pyrsistent==0.19.3 # via # -r requirements/base.txt # jsonschema +pytest==8.3.4 + # via -r requirements/test-tools.in python-dateutil==2.8.2 # via # -r requirements/base.txt @@ -544,6 +557,8 @@ qrcode==6.1 # via # -r requirements/base.txt # django-two-factor-auth +recommonmark==0.7.1 + # via -r requirements/test-tools.in redis==4.5.5 # via # -r requirements/base.txt @@ -588,11 +603,15 @@ soupsieve==2.4.1 # via beautifulsoup4 sphinx==6.2.1 # via - # -r requirements/dev.in + # -r requirements/test-tools.in + # recommonmark # sphinx-rtd-theme + # sphinx-tabs # sphinxcontrib-jquery sphinx-rtd-theme==1.2.0 - # via -r requirements/dev.in + # via -r requirements/test-tools.in +sphinx-tabs==3.4.7 + # via -r requirements/test-tools.in sphinxcontrib-applehelp==1.0.4 # via sphinx sphinxcontrib-devhelp==1.0.2 diff --git a/requirements/test-tools.in b/requirements/test-tools.in index 850fe83..fdae972 100644 --- a/requirements/test-tools.in +++ b/requirements/test-tools.in @@ -6,8 +6,15 @@ pyquery # integrates with webtest requests-mock tblib vcrpy +pytest # Code formatting black isort flake8 + +# Documentation +sphinx +sphinx-rtd-theme +sphinx-tabs +recommonmark diff --git a/src/objecttypes/__init__.py b/src/objecttypes/__init__.py index e69de29..b8d9077 100644 --- a/src/objecttypes/__init__.py +++ b/src/objecttypes/__init__.py @@ -0,0 +1,3 @@ +__version__ = "2.2.2" +__author__ = "Maykin Media" +__homepage__ = "https://github.com/maykinmedia/objecttypes-api"