build docs (#157)

Author: mr-c

.readthedocs.yml

@@ -0,0 +1,24 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+   - requirements: docs/requirements.txt
+   - method: pip
+     path: .

Makefile

@@ -26,15 +26,13 @@ PACKAGE=cwltest
 # `SHELL=bash` doesn't work for some, so don't use BASH-isms like
 # `[[` conditional expressions.
 PYSOURCES=$(wildcard ${MODULE}/**.py tests/*.py) setup.py
-DEVPKGS=diff_cover black pylint pep257 pydocstyle flake8 tox tox-pyenv \
-	isort wheel autoflake flake8-bugbear pyupgrade bandit \
-	-rtest-requirements.txt -rmypy-requirements.txt
+DEVPKGS=-rdev-requirements.txt -rtest-requirements.txt -rmypy-requirements.txt
 DEBDEVPKGS=pep8 python-autopep8 pylint python-coverage pydocstyle sloccount \
 	   python-flake8 python-mock shellcheck
 VERSION=2.2.$(shell TZ=UTC git log --first-parent --max-count=1 \
 	--format=format:%cd --date=format-local:%Y%m%d%H%M%S)
 
-## all         : default task
+## all                    : default task (install in dev mode)
 all: dev
 
 ## help                   : print this help message and exit
@@ -61,13 +59,18 @@ install: FORCE
 
 ## dev                    : install the cwltest package in dev mode
 dev: install-dep
+	pip install -U pip setuptools wheel
 	pip install -e .
 
 ## dist                   : create a module package for distribution
 dist: dist/${MODULE}-$(VERSION).tar.gz
 
 dist/${MODULE}-$(VERSION).tar.gz: $(SOURCES)
-	python setup.py sdist bdist_wheel
+	python -m build
+
+## docs                   : make the docs
+docs: FORCE
+	cd docs && $(MAKE) html
 
 ## clean                  : clean up all temporary / machine-generated files
 clean: FORCE
@@ -141,8 +144,8 @@ diff-cover.html: coverage.xml
 	diff-cover --compare-branch=main $^ --html-report $@
 
 ## test                   : run the cwltest test suite
-test: $(PYSOURCES) all
-	python setup.py test ${PYTEST_EXTRA}
+test: $(PYSOURCES)
+	python -m pytest -rs ${PYTEST_EXTRA}
 
 ## testcov                : run the cwltest test suite and collect coverage
 testcov: $(PYSOURCES)
@@ -161,21 +164,9 @@ list-author-emails:
 
 mypy3: mypy
 mypy: $(filter-out setup.py gittagger.py,$(PYSOURCES))
-	if ! test -f $(shell python3 -c 'import ruamel.yaml; import os.path; print(os.path.dirname(ruamel.yaml.__file__))')/py.typed ; \
-	then \
-		rm -Rf mypy-stubs/ruamel/yaml ; \
-		ln -s $(shell python3 -c 'import ruamel.yaml; import os.path; print(os.path.dirname(ruamel.yaml.__file__))') \
-			mypy-stubs/ruamel/ ; \
-	fi  # if minimally required ruamel.yaml version is 0.15.99 or greater, than the above can be removed
 	MYPYPATH=$$MYPYPATH:mypy-stubs mypy $^
 
 mypy_3.6: $(filter-out setup.py gittagger.py,$(PYSOURCES))
-	if ! test -f $(shell python3 -c 'import ruamel.yaml; import os.path; print(os.path.dirname(ruamel.yaml.__file__))')/py.typed ; \
-	then \
-		rm -Rf mypy-stubs/ruamel/yaml ; \
-		ln -s $(shell python3 -c 'import ruamel.yaml; import os.path; print(os.path.dirname(ruamel.yaml.__file__))') \
-			mypy-stubs/ruamel/ ; \
-	fi  # if minimally required ruamel.yaml version is 0.15.99 or greater, than the above can be removed
 	MYPYPATH=$$MYPYPATH:mypy-stubs mypy --python-version 3.6 $^
 
 pyupgrade: $(filter-out schema_salad/metaschema.py,$(PYSOURCES))
@@ -187,8 +178,8 @@ release-test: FORCE
 
 release: release-test
 	. testenv2/bin/activate && \
-		python testenv2/src/${PACKAGE}/setup.py sdist bdist_wheel
-	. testenv2/bin/activate && \
+		pip install build && \
+		python -m build testenv2/src/${PACKAGE} && \
 		pip install twine && \
 		twine upload testenv2/src/${PACKAGE}/dist/* && \
 		git tag ${VERSION} && git push --tags

dev-requirements.txt

@@ -0,0 +1,14 @@
+diff_cover
+black
+pylint
+pep257
+pydocstyle
+flake8
+tox < 4
+tox-pyenv
+isort
+wheel
+autoflake
+flake8-bugbear
+pyupgrade
+bandit

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)

docs/_static/favicon.ico

@@ -0,0 +1,102 @@
+# 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 --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+import time
+from datetime import datetime
+
+sys.path.insert(0, os.path.abspath(".."))
+
+
+# -- Project information -----------------------------------------------------
+
+build_date = datetime.utcfromtimestamp(
+    int(os.environ.get("SOURCE_DATE_EPOCH", time.time()))
+)
+# -- Project information -----------------------------------------------------
+
+project = "cwltest"
+copyright = (
+    f"2016 - {build_date.year}, Common Workflow Language project and contributors"
+)
+author = "Common Workflow Language project and contributors"
+
+
+# -- 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.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.inheritance_diagram",
+    "autoapi.extension",
+    "sphinx_autodoc_typehints",
+    "sphinx_rtd_theme",
+    "sphinxcontrib.autoprogram",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "schema_salad": ("https://schema-salad.readthedocs.io/en/stable/", None),
+    "rdflib": ("https://rdflib.readthedocs.io/en/6.2.0/", None),
+    #"ruamel.yaml": ("https://yaml.readthedocs.io/en/stable/", None),
+}
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# 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"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+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"]
+
+
+from pkg_resources import get_distribution
+
+release = get_distribution("cwltest").version
+version = ".".join(release.split(".")[:2])
+
+autoapi_dirs = ["../cwltest"]
+autodoc_typehints = "description"
+autoapi_keep_files = True
+autoapi_ignore = ["*.pyi"]
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-inheritance-diagram",
+    "show-module-summary",
+    "imported-members",
+    "special-members",
+]
+# sphinx-autodoc-typehints
+always_document_param_types = True
+# If False, do not add type info for undocumented parameters.
+# If True, add stub documentation for undocumented parameters to be able to add type info.

docs/conf.py

@@ -0,0 +1,17 @@
+.. include:: ../README.rst
+
+.. toctree::
+   :maxdepth: 2
+
+Command Line Options
+====================
+
+.. autoprogram:: cwltest.argparser:arg_parser()
+   :prog: cwltest
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/index.rst

@@ -0,0 +1,6 @@
+sphinx >= 2.2
+sphinx-rtd-theme==1.1.1
+sphinx-autoapi
+sphinx-autodoc-typehints
+typed_ast;python_version<'3.8'
+sphinxcontrib-autoprogram

docs/requirements.txt

@@ -19,7 +19,7 @@ else
 fi
 run_tests="bin/py.test --pyargs ${module}"
 pipver=20.3.3  # minimum required version of pip for Python 3.10
-setuptoolsver=50.0.0  # required for Python 3.10
+setuptoolsver=50.0.1  # required for Python 3.10
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )"
 
 rm -Rf testenv? || /bin/true
@@ -63,7 +63,7 @@ rm -f lib/python-wheels/setuptools* \
 # The following can fail if you haven't pushed your commits to ${repo}
 pip install -e "git+${repo}@${HEAD}#egg=${package}${extras}"
 pushd src/${package}
-pip install -rtest-requirements.txt
+pip install -rtest-requirements.txt build
 make dist
 make test
 cp dist/${package}*tar.gz ../../../testenv3/
@@ -84,7 +84,7 @@ rm -f lib/python-wheels/setuptools* \
 	&& pip install --force-reinstall -U pip==${pipver} \
         && pip install setuptools==${setuptoolsver} wheel
 package_tar=$(find . -name "${package}*tar.gz")
-pip install "-r${DIR}/test-requirements.txt"
+pip install "-r${DIR}/test-requirements.txt" build
 pip install "${package_tar}${extras}"
 mkdir out
 tar --extract --directory=out -z -f ${package}*.tar.gz