From 693907783ab9ef2a2ed6061dfb9acb18dacc3b96 Mon Sep 17 00:00:00 2001 From: Chris Stefano Date: Fri, 7 Nov 2025 14:50:42 +0000 Subject: [PATCH 1/8] install `sphinx-autodoc-typehints` --- pyproject.toml | 1 + uv.lock | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index e4384d1..fc12be0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -50,6 +50,7 @@ build = [ ] docs = [ "sphinx>=5.0", + "sphinx-autodoc-typehints>=3.0.1", "sphinx-rtd-theme>=1.0", ] diff --git a/uv.lock b/uv.lock index 67c8d1d..519077e 100644 --- a/uv.lock +++ b/uv.lock @@ -1437,6 +1437,37 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/31/53/136e9eca6e0b9dc0e1962e2c908fbea2e5ac000c2a2fbd9a35797958c48b/sphinx-8.2.3-py3-none-any.whl", hash = "sha256:4405915165f13521d875a8c29c8970800a0141c14cc5416a38feca4ea5d9b9c3", size = 3589741, upload-time = "2025-03-02T22:31:56.836Z" }, ] +[[package]] +name = "sphinx-autodoc-typehints" +version = "3.0.1" +source = { registry = "https://pypi.org/simple" } +resolution-markers = [ + "python_full_version < '3.11'", +] +dependencies = [ + { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/26/f0/43c6a5ff3e7b08a8c3b32f81b859f1b518ccc31e45f22e2b41ced38be7b9/sphinx_autodoc_typehints-3.0.1.tar.gz", hash = "sha256:b9b40dd15dee54f6f810c924f863f9cf1c54f9f3265c495140ea01be7f44fa55", size = 36282, upload-time = "2025-01-16T18:25:30.958Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/3c/dc/dc46c5c7c566b7ec5e8f860f9c89533bf03c0e6aadc96fb9b337867e4460/sphinx_autodoc_typehints-3.0.1-py3-none-any.whl", hash = "sha256:4b64b676a14b5b79cefb6628a6dc8070e320d4963e8ff640a2f3e9390ae9045a", size = 20245, upload-time = "2025-01-16T18:25:27.394Z" }, +] + +[[package]] +name = "sphinx-autodoc-typehints" +version = "3.5.2" +source = { registry = "https://pypi.org/simple" } +resolution-markers = [ + "python_full_version >= '3.12'", + "python_full_version == '3.11.*'", +] +dependencies = [ + { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/34/4f/4fd5583678bb7dc8afa69e9b309e6a99ee8d79ad3a4728f4e52fd7cb37c7/sphinx_autodoc_typehints-3.5.2.tar.gz", hash = "sha256:5fcd4a3eb7aa89424c1e2e32bedca66edc38367569c9169a80f4b3e934171fdb", size = 37839, upload-time = "2025-10-16T00:50:15.743Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/05/f2/9657c98a66973b7c35bfd48ba65d1922860de9598fbb535cd96e3f58a908/sphinx_autodoc_typehints-3.5.2-py3-none-any.whl", hash = "sha256:0accd043619f53c86705958e323b419e41667917045ac9215d7be1b493648d8c", size = 21184, upload-time = "2025-10-16T00:50:13.973Z" }, +] + [[package]] name = "sphinx-rtd-theme" version = "3.0.2" @@ -1629,6 +1660,8 @@ django-rq = [ docs = [ { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-autodoc-typehints", version = "3.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "sphinx-autodoc-typehints", version = "3.5.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, { name = "sphinx-rtd-theme" }, ] rq = [ @@ -1665,6 +1698,7 @@ dev = [ django-rq = [{ name = "django-rq", specifier = ">=3.1" }] docs = [ { name = "sphinx", specifier = ">=5.0" }, + { name = "sphinx-autodoc-typehints", specifier = ">=3.0.1" }, { name = "sphinx-rtd-theme", specifier = ">=1.0" }, ] rq = [ From 6974b4ba6ffc6db364e39bc0386cfb7290718718 Mon Sep 17 00:00:00 2001 From: Chris Stefano Date: Fri, 7 Nov 2025 14:56:49 +0000 Subject: [PATCH 2/8] add setting for BAT files --- .gitattributes | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitattributes b/.gitattributes index 058bf50..1a25d03 100644 --- a/.gitattributes +++ b/.gitattributes @@ -4,6 +4,8 @@ # Force the following filetypes to have unix eols, so Windows does not break them *.* text eol=lf +*.bat text eol=crlf + # Denote all files that are truly binary and should not be modified. *.7z binary *.bak binary From 21e2157b112caecaa2270c49e2478bf13b289832 Mon Sep 17 00:00:00 2001 From: Chris Stefano Date: Fri, 7 Nov 2025 16:28:31 +0000 Subject: [PATCH 3/8] add editor configuration for Makefile --- .editorconfig | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.editorconfig b/.editorconfig index 239fa20..3c83d70 100644 --- a/.editorconfig +++ b/.editorconfig @@ -11,5 +11,8 @@ trim_trailing_whitespace = true [*.py] indent_size = 4 +[Makefile] +indent_style = tab + [*.md] max_line_length = off From ee11b97c57971fa10eb347a2ce62126ce9397cd7 Mon Sep 17 00:00:00 2001 From: Chris Stefano Date: Fri, 7 Nov 2025 14:57:09 +0000 Subject: [PATCH 4/8] add sphinx quickstart --- docs/Makefile | 20 ++++++++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++++++ docs/source/_static/.keep | 0 docs/source/_templates/.keep | 0 docs/source/conf.py | 27 +++++++++++++++++++++++++++ docs/source/index.rst | 17 +++++++++++++++++ 6 files changed, 99 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/_static/.keep create mode 100644 docs/source/_templates/.keep create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /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 = source +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/make.bat b/docs/make.bat new file mode 100644 index 0000000..dc1312a --- /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=source +set BUILDDIR=build + +%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.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/.keep b/docs/source/_static/.keep new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/_templates/.keep b/docs/source/_templates/.keep new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..ed9089b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,27 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'tasktronaut' +copyright = '2025, Chris Stefano' +author = 'Chris Stefano' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..bb2360c --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,17 @@ +.. tasktronaut documentation master file, created by + sphinx-quickstart on Fri Nov 7 14:55:45 2025. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +tasktronaut documentation +========================= + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + From 7fa629816d67b849cca9d90cee3b90781eb148d2 Mon Sep 17 00:00:00 2001 From: Chris Stefano Date: Fri, 7 Nov 2025 16:34:35 +0000 Subject: [PATCH 5/8] add `build-docs` task --- Taskfile.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Taskfile.yml b/Taskfile.yml index 5f58803..3479e18 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -46,6 +46,13 @@ tasks: cmds: - uv run pytest --durations 10 + build-docs: + desc: Build HTML documentation + dir: docs + cmds: + - uv run sphinx-apidoc -o source/api ../src/tasktronaut + - uv run make html + # https://docs.astral.sh/uv/guides/package/#updating-your-version bump-version: desc: Bump Python package minor version From ff526ed854365b9714ce3c2b2097d41fec235d7d Mon Sep 17 00:00:00 2001 From: Chris Stefano Date: Fri, 7 Nov 2025 16:28:58 +0000 Subject: [PATCH 6/8] customize documentation config --- docs/source/conf.py | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index ed9089b..efdd54d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -6,22 +6,26 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'tasktronaut' -copyright = '2025, Chris Stefano' -author = 'Chris Stefano' +project = "tasktronaut" +author = "Chris Stefano" +copyright = f"2025, {author}" # pylint: disable=redefined-builtin # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = [ + "sphinx.ext.autodoc", # Auto-generate docs from docstrings + "sphinx_autodoc_typehints", # Include type hints in docs + "sphinx_rtd_theme", # Use Read the Docs theme +] -templates_path = ['_templates'] +templates_path = ["_templates"] exclude_patterns = [] - # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'alabaster' -html_static_path = ['_static'] +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] +html_title = "tasktronaut Documentation" From f3929e6512343af5e748b7f779ba6dfe75da7ce4 Mon Sep 17 00:00:00 2001 From: Chris Stefano Date: Fri, 7 Nov 2025 16:31:27 +0000 Subject: [PATCH 7/8] generate initial API documentation --- docs/source/api/modules.rst | 7 ++ docs/source/api/tasktronaut.backends.rst | 21 ++++++ docs/source/api/tasktronaut.rst | 93 ++++++++++++++++++++++++ 3 files changed, 121 insertions(+) create mode 100644 docs/source/api/modules.rst create mode 100644 docs/source/api/tasktronaut.backends.rst create mode 100644 docs/source/api/tasktronaut.rst diff --git a/docs/source/api/modules.rst b/docs/source/api/modules.rst new file mode 100644 index 0000000..b5675b4 --- /dev/null +++ b/docs/source/api/modules.rst @@ -0,0 +1,7 @@ +API Documentation +================= + +.. toctree:: + :maxdepth: 4 + + tasktronaut diff --git a/docs/source/api/tasktronaut.backends.rst b/docs/source/api/tasktronaut.backends.rst new file mode 100644 index 0000000..2146322 --- /dev/null +++ b/docs/source/api/tasktronaut.backends.rst @@ -0,0 +1,21 @@ +tasktronaut.backends package +============================ + +Submodules +---------- + +tasktronaut.backends.rq module +------------------------------ + +.. automodule:: tasktronaut.backends.rq + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: tasktronaut.backends + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/api/tasktronaut.rst b/docs/source/api/tasktronaut.rst new file mode 100644 index 0000000..bb22a52 --- /dev/null +++ b/docs/source/api/tasktronaut.rst @@ -0,0 +1,93 @@ +tasktronaut package +=================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + tasktronaut.backends + +Submodules +---------- + +tasktronaut.backend module +-------------------------- + +.. automodule:: tasktronaut.backend + :members: + :show-inheritance: + :undoc-members: + +tasktronaut.builder module +-------------------------- + +.. automodule:: tasktronaut.builder + :members: + :show-inheritance: + :undoc-members: + +tasktronaut.context module +-------------------------- + +.. automodule:: tasktronaut.context + :members: + :show-inheritance: + :undoc-members: + +tasktronaut.decorators module +----------------------------- + +.. automodule:: tasktronaut.decorators + :members: + :show-inheritance: + :undoc-members: + +tasktronaut.errors module +------------------------- + +.. automodule:: tasktronaut.errors + :members: + :show-inheritance: + :undoc-members: + +tasktronaut.process module +-------------------------- + +.. automodule:: tasktronaut.process + :members: + :show-inheritance: + :undoc-members: + +tasktronaut.steps module +------------------------ + +.. automodule:: tasktronaut.steps + :members: + :show-inheritance: + :undoc-members: + +tasktronaut.types module +------------------------ + +.. automodule:: tasktronaut.types + :members: + :show-inheritance: + :undoc-members: + +tasktronaut.utils module +------------------------ + +.. automodule:: tasktronaut.utils + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: tasktronaut + :members: + :show-inheritance: + :undoc-members: From 25a025f09972955d50c9209a10159391f9a3cd35 Mon Sep 17 00:00:00 2001 From: Chris Stefano Date: Fri, 7 Nov 2025 16:34:21 +0000 Subject: [PATCH 8/8] documentation boilerplate --- docs/.gitignore | 1 + docs/source/advanced.rst | 3 +++ docs/source/index.rst | 21 +++++++++++++-------- docs/source/user_guide.rst | 2 ++ 4 files changed, 19 insertions(+), 8 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/source/advanced.rst create mode 100644 docs/source/user_guide.rst diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..378eac2 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +build diff --git a/docs/source/advanced.rst b/docs/source/advanced.rst new file mode 100644 index 0000000..3493ee0 --- /dev/null +++ b/docs/source/advanced.rst @@ -0,0 +1,3 @@ +Advanced Use Cases +================== + diff --git a/docs/source/index.rst b/docs/source/index.rst index bb2360c..a582269 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,15 +3,20 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -tasktronaut documentation -========================= - -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. - +``tasktronaut`` Documentation +============================= .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: + user_guide + advanced + api/modules + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/user_guide.rst b/docs/source/user_guide.rst new file mode 100644 index 0000000..62b8c5a --- /dev/null +++ b/docs/source/user_guide.rst @@ -0,0 +1,2 @@ +User Guide +==========