API documentation test

Author: Fabien Coelho

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: FlaskTest documentation publication on GitHub
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+      - name: Install dependencies
+        run: make venv.update
+      - name: Check documentation syntax
+        run: make check.docs
+      - name: Generate documentation
+        run: make docs
+      - name: Upload to GitHub Pages
+        # FIXME what is the difference with deploy below?
+        uses: actions/upload-pages-artifact@v2
+  deploy:
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -158,3 +158,6 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# doc
+_site

Makefile

@@ -39,7 +39,7 @@ check.coverage: venv
 check.docs:
 	source venv/bin/activate
 	pymarkdown -d MD013 scan *.md
-	# sphinx-lint docs/
+	sphinx-lint docs/
 
 check: venv
 	source venv/bin/activate
@@ -51,20 +51,34 @@ check: venv
 	$(MAKE) check.pytest && \
 	$(MAKE) check.coverage
 
-.PHONY: clean clean.venv
+.PHONY: docs
+docs: venv
+	source venv/bin/activate
+	$(MAKE) -C docs html
+	find docs/_build -type d -print0 | xargs -0 chmod a+rx
+	find docs/_build -type f -print0 | xargs -0 chmod a+r
+	ln -s docs/_build/html _site
+
+.PHONY: clean
 clean:
-	$(RM) -r __pycache__ */__pycache__ dist build .mypy_cache .pytest_cache .ruff_cache
+	$(RM) -r __pycache__ */__pycache__ dist build .mypy_cache .pytest_cache .ruff_cache _site
 	$(RM) $(F.pdf)
 	$(MAKE) -C tests clean
+	$(MAKE) -C docs clean
 
+.PHONY: clean.venv
 clean.venv: clean
 	$(RM) -r venv *.egg-info
 
+.PHONY: venv.update
+venv.update:
+	$(PIP) install -U pip
+	$(PIP) install -e .[dev,doc]
+
 # for local testing
 venv:
 	$(PYTHON) -m venv venv
-	$(PIP) install -U pip
-	$(PIP) install -e .[dev,doc]
+	$(MAKE) venv.update
 
 $(MODULE).egg-info: venv
 	$(PIP) install -e .

README.md

@@ -190,8 +190,9 @@ please report any [issues](https://github.com/zx80/flask-tester/issues).
 
 ## Versions
 
-### ? on ?
+### 1.3 on ?
 
+Generate API documentation.
 Cleaner code.
 
 ### 1.2 on 2024-03-15

docs/Makefile

@@ -0,0 +1,24 @@
+#
+# Minimal makefile for Sphinx documentation
+#
+# try: "make help"
+
+# 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".
+.PHONY: default
+default: help
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: clean
+clean:
+	$(RM) -r _build

docs/conf.py

@@ -0,0 +1,35 @@
+#
+# 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 = "FlaskTester"
+copyright = "2024, Calvin"
+author = "Calvin"
+
+from importlib.metadata import version as pkg_version
+release = pkg_version("FlaskTester")
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+source_suffix = [".md", ".rst"]
+
+extensions = ["myst_parser", "autoapi.extension"]
+
+autoapi_dirs = [".."]
+autoapi_ignore = ["*/venv/*", "*/tests/*"]
+autoapi_options = ["members", "show-inheritance", "show-module-summary", "special-members", "imported-members"]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"  # ReadTheDocs Theme
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,15 @@
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents
+
+   API <autoapi>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "FlaskTester"
-version = "1.2"
+version = "1.3"
 authors = [ { name = "Fabien Coelho", email = "[email protected]" } ]
 description = "Pytest fixtures for Flask internal and external authenticated tests"
 readme = "README.md"
@@ -35,7 +35,7 @@ package = "https://pypi.org/project/FlaskTester/"
 # various dev tools
 dev = ["mypy", "pyright", "ruff", "coverage", "pymarkdownlnt!=0.9.5", "build", "twine", "wheel", "types-flask", "types-requests", "FlaskSimpleAuth", "passlib"]
 # documentation generation
-doc = ["sphinx", "sphinx_rtd_theme", "sphinx-autoapi", "sphinx-lint"]
+doc = ["sphinx", "sphinx_rtd_theme", "sphinx-autoapi", "sphinx-lint", "myst_parser"]
 
 [tool.setuptools]
 py-modules = [ "FlaskTester" ]