From d5d0f83b2802bbf8007c7c1eefe6b34ed09dacfe Mon Sep 17 00:00:00 2001 From: Sidney Richards Date: Thu, 19 Dec 2024 15:27:20 +0100 Subject: [PATCH] Include sphinx packages in CI deps --- docs/Makefile | 20 ++++++++++ docs/check_sphinx.py | 17 ++++++++ docs/conf.py | 90 +++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 2 + docs/make.bat | 35 +++++++++++++++++ requirements/base.txt | 10 ++--- requirements/ci.in | 4 ++ requirements/ci.txt | 44 ++++++++++++++++++--- requirements/dev.txt | 6 +-- 9 files changed, 211 insertions(+), 17 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/check_sphinx.py create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat 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..fc2a50e --- /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 objects # 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 = objects.__author__ + +# The full version, including alpha/beta/rc tags +release = objects.__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/base.txt b/requirements/base.txt index 90ac5d5..2fd5cc1 100644 --- a/requirements/base.txt +++ b/requirements/base.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.11 +# This file is autogenerated by pip-compile with Python 3.12 # by the following command: # # pip-compile --no-emit-index-url requirements/base.in @@ -195,9 +195,7 @@ drf-nested-routers==0.94.1 # -r requirements/base.in # commonground-api-common drf-spectacular[sidecar]==0.27.2 - # via - # drf-spectacular - # open-api-framework + # via open-api-framework drf-spectacular-sidecar==2024.7.1 # via drf-spectacular drf-yasg==1.21.7 @@ -277,9 +275,7 @@ pydantic==2.9.2 pydantic-core==2.23.4 # via pydantic pydantic-settings[yaml]==2.6.1 - # via - # django-setup-configuration - # pydantic-settings + # via django-setup-configuration pyjwt==2.7.0 # via # commonground-api-common diff --git a/requirements/ci.in b/requirements/ci.in index ec8ac8a..9ae16b9 100644 --- a/requirements/ci.in +++ b/requirements/ci.in @@ -1,2 +1,6 @@ codecov coverage + +# Documentation +sphinx +sphinx_rtd_theme diff --git a/requirements/ci.txt b/requirements/ci.txt index 3ca4980..46f3d40 100644 --- a/requirements/ci.txt +++ b/requirements/ci.txt @@ -1,9 +1,11 @@ # -# This file is autogenerated by pip-compile with Python 3.11 +# This file is autogenerated by pip-compile with Python 3.12 # by the following command: # # 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 @@ -262,7 +266,6 @@ django-solo==2.0.0 django-two-factor-auth[phonenumberslite,webauthn]==1.16.0 # via # -r requirements/base.txt - # django-two-factor-auth # maykin-2fa django-webtest==1.9.10 # via -r requirements/test-tools.in @@ -290,6 +293,10 @@ djangorestframework-inclusions==1.2.0 # via # -r requirements/base.txt # open-api-framework +docutils==0.21.2 + # via + # sphinx + # sphinx-rtd-theme drf-nested-routers==0.94.1 # via # -r requirements/base.txt @@ -297,7 +304,6 @@ drf-nested-routers==0.94.1 drf-spectacular[sidecar]==0.27.2 # via # -r requirements/base.txt - # drf-spectacular # open-api-framework drf-spectacular-sidecar==2024.7.1 # via @@ -348,6 +354,8 @@ idna==3.7 # -r requirements/base.txt # requests # yarl +imagesize==1.4.1 + # via sphinx inflection==0.5.1 # via # -r requirements/base.txt @@ -371,6 +379,7 @@ jinja2==3.1.4 # via # -r requirements/base.txt # coreschema + # sphinx josepy==1.13.0 # via # -r requirements/base.txt @@ -402,7 +411,6 @@ mozilla-django-oidc==4.0.0 mozilla-django-oidc-db[django-setup-configuration]==0.21.1 # via # -r requirements/base.txt - # mozilla-django-oidc-db # open-api-framework multidict==6.0.5 # via yarl @@ -427,6 +435,7 @@ packaging==23.1 # -r requirements/base.txt # black # drf-yasg + # sphinx pathspec==0.12.1 # via black phonenumberslite==8.13.30 @@ -466,9 +475,10 @@ pydantic-settings[yaml]==2.6.1 # via # -r requirements/base.txt # django-setup-configuration - # pydantic-settings pyflakes==3.2.0 # via flake8 +pygments==2.18.0 + # via sphinx pyjwt==2.7.0 # via # -r requirements/base.txt @@ -534,6 +544,7 @@ requests==2.32.3 # open-api-framework # requests-mock # sharing-configs + # sphinx # zgw-consumers requests-mock==1.12.1 # via @@ -556,8 +567,31 @@ 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/ci.in + # sphinx-rtd-theme + # sphinxcontrib-jquery +sphinx-rtd-theme==3.0.2 + # via -r requirements/ci.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.txt b/requirements/dev.txt index 7a4b1c3..869eb98 100644 --- a/requirements/dev.txt +++ b/requirements/dev.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.11 +# This file is autogenerated by pip-compile with Python 3.12 # by the following command: # # pip-compile --no-emit-index-url --output-file=requirements/dev.txt requirements/base.txt requirements/dev.in requirements/test-tools.in @@ -273,7 +273,6 @@ django-solo==2.0.0 django-two-factor-auth[phonenumberslite,webauthn]==1.16.0 # via # -r requirements/base.txt - # django-two-factor-auth # maykin-2fa django-webtest==1.9.10 # via -r requirements/test-tools.in @@ -312,7 +311,6 @@ drf-nested-routers==0.94.1 drf-spectacular[sidecar]==0.27.2 # via # -r requirements/base.txt - # drf-spectacular # open-api-framework drf-spectacular-sidecar==2024.7.1 # via @@ -420,7 +418,6 @@ mozilla-django-oidc==4.0.0 mozilla-django-oidc-db[django-setup-configuration]==0.21.1 # via # -r requirements/base.txt - # mozilla-django-oidc-db # open-api-framework multidict==6.0.5 # via yarl @@ -488,7 +485,6 @@ pydantic-settings[yaml]==2.6.1 # via # -r requirements/base.txt # django-setup-configuration - # pydantic-settings pyflakes==3.0.1 # via flake8 pygments==2.15.1