Type hints, test building docs

.github/workflows/docs.yml

@@ -0,0 +1,23 @@
+name: docs
+
+on: [push, pull_request]
+
+jobs:
+  docs:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.10'
+      - name: Install dependencies
+        run: |
+          python setup.py develop
+          pip install -r docs/requirements.txt
+      - name: Build docs
+        run: |
+          cd docs
+          make html

.github/workflows/tests.yml

@@ -11,6 +11,7 @@ jobs:
       max-parallel: 5
       matrix:
         python-version: [3.6, 3.7, 3.8, 3.9, '3.10']
+      fail-fast: false
 
     steps:
       - uses: actions/checkout@v2

docs/Makefile

@@ -10,7 +10,7 @@ BUILDDIR      = _build
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -v -T -E -W --keep-going -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 

docs/conf.py

@@ -12,7 +12,12 @@
 
 # -- General configuration ----------------------------------------------------
 
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx_rtd_theme"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx_rtd_theme",
+    "sphinx_autodoc_typehints",
+]
 
 templates_path = ["_templates"]
 

docs/developer.rst

@@ -125,8 +125,11 @@ endpoints data.
 .. autoclass:: pypuppetdb.types.Fact
 .. autoclass:: pypuppetdb.types.Resource
 .. autoclass:: pypuppetdb.types.Event
+   :members:
+   :special-members: __init__
 .. autoclass:: pypuppetdb.types.Report
    :members:
+   :special-members: __init__
 .. autoclass:: pypuppetdb.types.Catalog
    :members:
 .. autoclass:: pypuppetdb.types.Edge

docs/requirements.txt

@@ -1,2 +1,3 @@
-sphinx
-sphinx-rtd-theme
+Sphinx>=4.0.0.b1,<5
+sphinx-rtd-theme>=0.5.1,<1
+sphinx-autodoc-typehints>=1.12.0,<2

pypuppetdb/api/query.py

@@ -3,6 +3,7 @@
 
 import logging
 from datetime import datetime
+from typing import Iterator
 
 from pypuppetdb.QueryBuilder import (EqualsOperator)
 from pypuppetdb.api.base import BaseAPI
@@ -18,7 +19,7 @@ class QueryAPI(BaseAPI):
     """
 
     def nodes(self, unreported=2, with_status=False, with_event_numbers=True,
-              **kwargs):
+              **kwargs) -> Iterator[Node]:
         r"""Query for nodes by either name or query. If both aren't
         provided this will return a list of all nodes. This method
         also (optionally) fetches the nodes status and (optionally)
@@ -211,7 +212,7 @@ def catalog(self, node):
         catalogs = self.catalogs(path=node)
         return next(catalog for catalog in catalogs)
 
-    def catalogs(self, **kwargs):
+    def catalogs(self, **kwargs) -> Iterator[Catalog]:
         r"""Get the catalog information from the infrastructure based on path
         and/or query results. It is strongly recommended to include query
         and/or paging parameters for this endpoint to prevent large result
@@ -232,7 +233,7 @@ def catalogs(self, **kwargs):
         for catalog in catalogs:
             yield Catalog.create_from_dict(catalog)
 
-    def events(self, **kwargs):
+    def events(self, **kwargs) -> Iterator[Event]:
         r"""A report is made up of events which can be queried either
         individually or based on their associated report hash. It is strongly
         recommended to include query and/or paging parameters for this