docs: intersphinx links, other cleanups

Author: mr-c

Makefile

@@ -28,7 +28,7 @@ EXTRAS=
 # `[[` conditional expressions.
 PYSOURCES=$(filter-out $(MODULE)/parser/cwl_v%,$(shell find $(MODULE) -name "*.py")) \
 	  $(wildcard tests/*.py) create_cwl_from_objects.py load_cwl_by_path.py \
-	  setup.py ${MODULE}/parser/cwl_v1_?_utils.py
+	  setup.py ${MODULE}/parser/cwl_v1_?_utils.py docs/conf.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

cwl_utils/cite_extract.py

@@ -10,7 +10,7 @@
 
 
 def arg_parser() -> argparse.ArgumentParser:
-    """Argument parser."""
+    """Construct the argument parser."""
     parser = argparse.ArgumentParser(
         description="Print information about software used in a CWL document (Workflow or CommandLineTool). "
         "For CWL Workflows, all steps will also be searched (recursively)."

cwl_utils/parser/__init__.py

@@ -14,26 +14,36 @@
 LoadingOptions = Union[
     cwl_v1_0.LoadingOptions, cwl_v1_1.LoadingOptions, cwl_v1_2.LoadingOptions
 ]
+"""Type union for a CWL v1.x LoadingOptions object."""
 Saveable = Union[cwl_v1_0.Saveable, cwl_v1_1.Saveable, cwl_v1_2.Saveable]
+"""Type union for a CWL v1.x Savable object."""
 Workflow = Union[cwl_v1_0.Workflow, cwl_v1_1.Workflow, cwl_v1_2.Workflow]
+"""Type union for a CWL v1.x Workflow object."""
 WorkflowTypes = (cwl_v1_0.Workflow, cwl_v1_1.Workflow, cwl_v1_2.Workflow)
 WorkflowStep = Union[
     cwl_v1_0.WorkflowStep, cwl_v1_1.WorkflowStep, cwl_v1_2.WorkflowStep
 ]
+"""Type union for a CWL v1.x WorkflowStep object."""
 CommandLineTool = Union[
     cwl_v1_0.CommandLineTool, cwl_v1_1.CommandLineTool, cwl_v1_2.CommandLineTool
 ]
+"""Type union for a CWL v1.x CommandLineTool object."""
 ExpressionTool = Union[
     cwl_v1_0.ExpressionTool, cwl_v1_1.ExpressionTool, cwl_v1_2.ExpressionTool
 ]
+"""Type union for a CWL v1.x ExpressionTool object."""
 DockerRequirement = Union[
     cwl_v1_0.DockerRequirement, cwl_v1_1.DockerRequirement, cwl_v1_2.DockerRequirement
 ]
+"""Type union for a CWL v1.x DockerRequirement object."""
 DockerRequirementTypes = (
     cwl_v1_0.DockerRequirement,
     cwl_v1_1.DockerRequirement,
     cwl_v1_2.DockerRequirement,
 )
+Process = Union[Workflow, CommandLineTool, ExpressionTool, cwl_v1_2.Operation]
+"""Type Union for a CWL v1.x Process object."""
+
 _Loader = Union[cwl_v1_0._Loader, cwl_v1_1._Loader, cwl_v1_2._Loader]
 
 
@@ -52,11 +62,9 @@ def _get_id_from_graph(yaml: MutableMapping[str, Any], id_: Optional[str]) -> An
 def cwl_version(yaml: Any) -> Optional[str]:
     """Return the cwlVersion of a YAML object.
 
-    Args:
-        yaml: A YAML object
+    :param yaml: ruamel.yaml object for a CWL document
 
-    Raises:
-        ValidationException: If `yaml` is not a MutableMapping.
+    :raises ValidationException: If `yaml` is not a MutableMapping.
     """
     if not isinstance(yaml, MutableMapping):
         raise ValidationException("MutableMapping is required")
@@ -162,7 +170,7 @@ def save(
     base_url: str = "",
     relative_uris: bool = True,
 ) -> Any:
-    """Convert a given CWL object into a built-in typed object."""
+    """Convert a CWL Python object into a JSON/YAML serializable object."""
     if (
         isinstance(val, cwl_v1_0.Saveable)
         or isinstance(val, cwl_v1_1.Saveable)
@@ -194,6 +202,7 @@ def save(
 
 
 def is_process(v: Any) -> bool:
+    """Test to see if the object is a CWL v1.x Python Process object."""
     return (
         isinstance(v, cwl_v1_0.Process)
         or isinstance(v, cwl_v1_1.Process)
@@ -202,4 +211,5 @@ def is_process(v: Any) -> bool:
 
 
 def version_split(version: str) -> MutableSequence[int]:
+    """Split a cwlVersion value into its numerical components."""
     return [int(v) for v in version[1:].split(".")]

cwl_utils/parser/utils.py

@@ -4,83 +4,76 @@
 
 from schema_salad.exceptions import ValidationException
 
-import cwl_utils.parser
-import cwl_utils.parser.cwl_v1_0
-import cwl_utils.parser.cwl_v1_0_utils
-import cwl_utils.parser.cwl_v1_1
-import cwl_utils.parser.cwl_v1_1_utils
-import cwl_utils.parser.cwl_v1_2
-import cwl_utils.parser.cwl_v1_2_utils
+from . import (
+    Process,
+    Workflow,
+    cwl_v1_0,
+    cwl_v1_0_utils,
+    cwl_v1_1,
+    cwl_v1_1_utils,
+    cwl_v1_2,
+    cwl_v1_2_utils,
+)
 
 
-def convert_stdstreams_to_files(
-    process: Union[
-        cwl_utils.parser.Workflow,
-        cwl_utils.parser.CommandLineTool,
-        cwl_utils.parser.ExpressionTool,
-    ]
-) -> None:
+def convert_stdstreams_to_files(process: Process) -> None:
     """Convert stdin, stdout and stderr type shortcuts to files."""
-    if isinstance(process, cwl_utils.parser.cwl_v1_0.CommandLineTool):
-        cwl_utils.parser.cwl_v1_0_utils.convert_stdstreams_to_files(process)
-    elif isinstance(process, cwl_utils.parser.cwl_v1_1.CommandLineTool):
-        cwl_utils.parser.cwl_v1_1_utils.convert_stdstreams_to_files(process)
-    elif isinstance(process, cwl_utils.parser.cwl_v1_2.CommandLineTool):
-        cwl_utils.parser.cwl_v1_2_utils.convert_stdstreams_to_files(process)
+    if isinstance(process, cwl_v1_0.CommandLineTool):
+        cwl_v1_0_utils.convert_stdstreams_to_files(process)
+    elif isinstance(process, cwl_v1_1.CommandLineTool):
+        cwl_v1_1_utils.convert_stdstreams_to_files(process)
+    elif isinstance(process, cwl_v1_2.CommandLineTool):
+        cwl_v1_2_utils.convert_stdstreams_to_files(process)
 
 
 def type_for_source(
-    process: Union[
-        cwl_utils.parser.CommandLineTool,
-        cwl_utils.parser.Workflow,
-        cwl_utils.parser.ExpressionTool,
-    ],
+    process: Process,
     sourcenames: Union[str, List[str]],
-    parent: Optional[cwl_utils.parser.Workflow] = None,
+    parent: Optional[Workflow] = None,
     linkMerge: Optional[str] = None,
     pickValue: Optional[str] = None,
 ) -> Any:
     """Determine the type for the given sourcenames."""
     if process.cwlVersion == "v1.0":
-        cwl_utils.parser.cwl_v1_0_utils.type_for_source(
+        cwl_v1_0_utils.type_for_source(
             cast(
                 Union[
-                    cwl_utils.parser.cwl_v1_0.CommandLineTool,
-                    cwl_utils.parser.cwl_v1_0.Workflow,
-                    cwl_utils.parser.cwl_v1_0.ExpressionTool,
+                    cwl_v1_0.CommandLineTool,
+                    cwl_v1_0.Workflow,
+                    cwl_v1_0.ExpressionTool,
                 ],
                 process,
             ),
             sourcenames,
-            cast(cwl_utils.parser.cwl_v1_0.Workflow, parent),
+            cast(Optional[cwl_v1_0.Workflow], parent),
             linkMerge,
         )
     elif process.cwlVersion == "v1.1":
-        cwl_utils.parser.cwl_v1_1_utils.type_for_source(
+        cwl_v1_1_utils.type_for_source(
             cast(
                 Union[
-                    cwl_utils.parser.cwl_v1_1.CommandLineTool,
-                    cwl_utils.parser.cwl_v1_1.Workflow,
-                    cwl_utils.parser.cwl_v1_1.ExpressionTool,
+                    cwl_v1_1.CommandLineTool,
+                    cwl_v1_1.Workflow,
+                    cwl_v1_1.ExpressionTool,
                 ],
                 process,
             ),
             sourcenames,
-            cast(cwl_utils.parser.cwl_v1_1.Workflow, parent),
+            cast(Optional[cwl_v1_1.Workflow], parent),
             linkMerge,
         )
     elif process.cwlVersion == "v1.2":
-        cwl_utils.parser.cwl_v1_2_utils.type_for_source(
+        cwl_v1_2_utils.type_for_source(
             cast(
                 Union[
-                    cwl_utils.parser.cwl_v1_2.CommandLineTool,
-                    cwl_utils.parser.cwl_v1_2.Workflow,
-                    cwl_utils.parser.cwl_v1_2.ExpressionTool,
+                    cwl_v1_2.CommandLineTool,
+                    cwl_v1_2.Workflow,
+                    cwl_v1_2.ExpressionTool,
                 ],
                 process,
             ),
             sourcenames,
-            cast(cwl_utils.parser.cwl_v1_2.Workflow, parent),
+            cast(Optional[cwl_v1_2.Workflow], parent),
             linkMerge,
             pickValue,
         )

docs/_static/favicon.ico

@@ -2,7 +2,7 @@
 #
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Path setup --------------------------------------------------------------
 
@@ -12,14 +12,20 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('..'))
+import time
+from datetime import datetime
+
+sys.path.insert(0, os.path.abspath(".."))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'cwl-utils'
-copyright = '2019, CWL Community'
-author = 'CWL Community'
+build_date = datetime.utcfromtimestamp(
+    int(os.environ.get("SOURCE_DATE_EPOCH", time.time()))
+)
+project = "cwl-utils: Python utilities Common Workflow Language documents"
+copyright = f"2019 — {build_date.year} CWL Community"
+author = "Common Workflow Language Project contributors"
 
 
 # -- General configuration ---------------------------------------------------
@@ -28,22 +34,31 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-        "sphinx.ext.autodoc",
-        "sphinx.ext.autosummary",
-        "sphinx.ext.inheritance_diagram",
-        "autoapi.extension",
-        "sphinx_autodoc_typehints",
-        "sphinx_rtd_theme",
-        "sphinxcontrib.autoprogram"
+    "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']
+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']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -53,22 +68,37 @@
 #
 html_theme = "sphinx_rtd_theme"
 
+# html_logo = "_static/logo.png"
+html_favicon = "_static/favicon.ico"
+
+html_theme_options = {
+    "collapse_navigation": False,
+}
+
 # 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_static_path = ["_static"]
 
 from pkg_resources import get_distribution
-release = get_distribution('cwl-utils').version
-version = '.'.join(release.split('.')[:2])
 
-autoapi_dirs = ['../cwl_utils']
-autodoc_typehints = 'description'
+release = get_distribution("cwl-utils").version
+version = ".".join(release.split(".")[:2])
+
+autoapi_dirs = ["../cwl_utils"]
+autodoc_typehints = "description"
 autoapi_keep_files = True
-autoapi_ignore = ['*migrations*', '*.pyi']
-autoapi_options = [ 'members', 'undoc-members', 'show-inheritance', 'show-inheritance-diagram', 'show-module-summary', 'imported-members', 'special-members' ]
-#sphinx-autodoc-typehints
+autoapi_ignore = ["*migrations*", "*.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.
-