Improve docs build and fix warnings (#150)

.github/workflows/ci_cd.yml

@@ -34,6 +34,28 @@ jobs:
       - name: Lint
         run: hatch run lint
 
+  docs:
+    name: build docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Install hatch
+        run: pipx install hatch
+
+      - name: Build docs
+        run: hatch run docs:build --fail-on-warning
+
   build:
     name: build
     runs-on: ubuntu-latest

README.rst

@@ -61,7 +61,7 @@ Using ``pip`` package manager (requires pip 1.8+):
 
     pip install --upgrade pook
 
-Or install the latest sources from Github:
+Or install the latest sources from GitHub:
 
 .. code:: bash
 

docs/api.rst

@@ -3,75 +3,20 @@
 API Documentation
 =================
 
+
 Core API
 --------
 
-.. toctree::
-
-   pook.activate <http://pook.readthedocs.io/en/latest/api.html#pook.activate>
-   pook.on <http://pook.readthedocs.io/en/latest/api.html#pook.on>
-   pook.disable <http://pook.readthedocs.io/en/latest/api.html#pook.disable>
-   pook.off <http://pook.readthedocs.io/en/latest/api.html#pook.off>
-   pook.reset <http://pook.readthedocs.io/en/latest/api.html#pook.reset>
-   pook.engine <http://pook.readthedocs.io/en/latest/api.html#pook.engine>
-   pook.use <http://pook.readthedocs.io/en/latest/api.html#pook.use>
-   pook.context <http://pook.readthedocs.io/en/latest/api.html#pook.context>
-   pook.enable_network <http://pook.readthedocs.io/en/latest/api.html#pook.enable_network>
-   pook.disable_network <http://pook.readthedocs.io/en/latest/api.html#pook.disable_network>
-   pook.use_network <http://pook.readthedocs.io/en/latest/api.html#pook.use_network>
-   pook.use_network_filter <http://pook.readthedocs.io/en/latest/api.html#pook.use_network_filter>
-   pook.flush_network_filters <http://pook.readthedocs.io/en/latest/api.html#pook.flush_network_filters>
-   pook.mock <http://pook.readthedocs.io/en/latest/api.html#pook.mock>
-   pook.get <http://pook.readthedocs.io/en/latest/api.html#pook.get>
-   pook.put <http://pook.readthedocs.io/en/latest/api.html#pook.put>
-   pook.delete <http://pook.readthedocs.io/en/latest/api.html#pook.delete>
-   pook.head <http://pook.readthedocs.io/en/latest/api.html#pook.head>
-   pook.patch <http://pook.readthedocs.io/en/latest/api.html#pook.patch>
-   pook.options <http://pook.readthedocs.io/en/latest/api.html#pook.options>
-   pook.pending <http://pook.readthedocs.io/en/latest/api.html#pook.pending>
-   pook.ispending <http://pook.readthedocs.io/en/latest/api.html#pook.ispending>
-   pook.pending_mocks <http://pook.readthedocs.io/en/latest/api.html#pook.pending_mocks>
-   pook.unmatched_requests <http://pook.readthedocs.io/en/latest/api.html#pook.unmatched_requests>
-   pook.unmatched <http://pook.readthedocs.io/en/latest/api.html#pook.unmatched>
-   pook.isunmatched <http://pook.readthedocs.io/en/latest/api.html#pook.isunmatched>
-   pook.isactive <http://pook.readthedocs.io/en/latest/api.html#pook.isactive>
-   pook.isdone <http://pook.readthedocs.io/en/latest/api.html#pook.isdone>
-   pook.regex <http://pook.readthedocs.io/en/latest/api.html#pook.regex>
-
-   pook.Mock <http://pook.readthedocs.io/en/latest/api.html#pook.Mock>
-   pook.Engine <http://pook.readthedocs.io/en/latest/api.html#pook.Engine>
-   pook.Request <http://pook.readthedocs.io/en/latest/api.html#pook.Request>
-   pook.Response <http://pook.readthedocs.io/en/latest/api.html#pook.Response>
-   pook.MockEngine <http://pook.readthedocs.io/en/latest/api.html#pook.MockEngine>
-   pook.MatcherEngine <http://pook.readthedocs.io/en/latest/api.html#pook.MatcherEngine>
-
-
 .. automodule:: pook
     :members:
+    :member-order: bysource
     :undoc-members:
     :show-inheritance:
 
 
 Matchers API
 ------------
 
-.. toctree::
-
-   pook.matchers.init <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.init>
-   pook.matchers.add <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.add>
-   pook.matchers.get <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.get>
-   pook.matchers.BaseMatcher <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.BaseMatcher>
-   pook.matchers.MethodMatcher <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.MethodMatcher>
-   pook.matchers.URLMatcher <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.URLMatcher>
-   pook.matchers.HeadersMatcher <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.HeadersMatcher>
-   pook.matchers.PathMatcher <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.PathMatcher>
-   pook.matchers.BodyMatcher <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.BodyMatcher>
-   pook.matchers.XMLMatcher <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.XMLMatcher>
-   pook.matchers.JSONMatcher <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.JSONMatcher>
-   pook.matchers.JSONSchemaMatcher <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.JSONSchemaMatcher>
-   pook.matchers.QueryMatcher <http://pook.readthedocs.io/en/latest/api.html#pook.matchers.QueryMatcher>
-
-
 .. automodule:: pook.matchers
     :members:
     :undoc-members:
@@ -81,16 +26,8 @@ Matchers API
 Interceptors API
 ----------------
 
-.. toctree::
-
-   pook.interceptors.add <http://pook.readthedocs.io/en/latest/api.html#pook.interceptors.add>
-   pook.interceptors.get <http://pook.readthedocs.io/en/latest/api.html#pook.interceptors.get>
-   pook.interceptors.BaseInterceptor <http://pook.readthedocs.io/en/latest/api.html#pook.interceptors.BaseInterceptor>
-   pook.interceptors.Urllib3Interceptor <http://pook.readthedocs.io/en/latest/api.html#pook.interceptors.Urllib3Interceptor>
-   pook.interceptors.AIOHTTPInterceptor <http://pook.readthedocs.io/en/latest/api.html#pook.interceptors.AIOHTTPInterceptor>
-   pook.interceptors.HTTPClientInterceptor <http://pook.readthedocs.io/en/latest/api.html#pook.interceptors.HTTPClientInterceptor>
-
 .. automodule:: pook.interceptors
     :members:
     :undoc-members:
     :show-inheritance:
+    :exclude-members: activate, disable

docs/conf.py

@@ -22,7 +22,6 @@
 sys.path.insert(0, os.path.abspath(".."))
 
 import pook  # noqa
-import sphinx_rtd_theme
 
 # -- General configuration ------------------------------------------------
 
@@ -130,9 +129,8 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = 'alabaster'
 html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -166,7 +164,7 @@
 # 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"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -350,4 +348,4 @@
 # texinfo_no_detailmenu = False
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"http://docs.python.org/": None}
+# intersphinx_mapping = {"http://docs.python.org/": None}

docs/faq.rst

@@ -24,15 +24,15 @@ Does ``pook`` mock out all the outgoing HTTP traffic from my app?
 Yes, that's the default behaviour: any outgoing HTTP traffic across the supported
 HTTP clients will be intercepted by ``pook``.
 
-In case that an outgoing traffic does not match any mock expectation, an exception error
+In case that an outgoing request does not match any mock expectation, an exception error
 will be raised, telling you no mock was matched in order to review or fix your code accordingly.
 
-You can for sure change this behaviour and don't raise any exception if no mock definition can be matched.
+You can change this behaviour and don't raise any exception if no mock definition can be matched.
 
-You can change this enabling the real networking mode via ``pook.enable_network()``.
+You can change this enabling the real networking mode via :func:`pook.enable_network`.
 
 
-Can I use ``pook`` in a non testing environment?
+Can I use ``pook`` in a non-testing environment?
 ------------------------------------------------
 
 Absolutely. ``pook`` is testing environment agnostic.
@@ -49,17 +49,17 @@ Can I use ``pook`` with a custom HTTP traffic mock interceptor engine?
 Yes, you can. ``pook`` is very modular and open for extensibility.
 
 You can programmatically define the HTTP traffic mock engine you want to use via
-``pook.set_mock_engine(engine)``. This will replace the built-in one.
+:func:`pook.set_mock_engine`. This will replace the built-in one.
 
 This can be particularly useful if you are already using another HTTP mocking
 engine that satisfy your needs, but you want to take benefit of ``pook``
 features, versatility and simple to use expressive API.
 
-For mock engine implementation details, see ``pook.MockEngine`` API documentation.
+For mock engine implementation details, see :any:`pook.MockEngine` API documentation.
 
 
 Can I use ``pook`` with any test framework?
 -------------------------------------------
 
-Yes. ``pook`` is test framework agnostic.
+Yes. ``pook`` is framework-agnostic.
 You can use it within ``unittest``, ``pytest`` or others.

docs/how_it_works.rst

@@ -5,12 +5,12 @@ HTTP traffic interception
 -------------------------
 
 In a nutshell, ``pook`` uses ``unittest.mock`` standard Python package in order
-to patch external library objects, allowing ``pook`` HTTP interceptor adapter to patch any third-party packages
+to patch external library objects, allowing ``pook`` HTTP interceptor adaptor to patch any third-party packages
 and intercept specific function calls.
 
 ``pook`` entirely relies on this interception strategy, therefore in the meantime ``pook`` is active,
 any outgoing HTTP traffic intercepted by the supported HTTP clients won't imply any real TCP networking,
-except if you enabled the real networking mode via ``pook.enable_network()``, which in
+except if you enabled the real networking mode via :func:`pook.enable_network`, which in
 that case real network traffic can be established.
 
 Worth clarifying that ``pook`` only works at Python programmatic runtime level.
@@ -33,16 +33,16 @@ will be ignored. Once the first one expires, the subsequent mock definition in t
 Real networking mode
 --------------------
 
-By default real networking mode is disabled.
-This basically means that real networking will not happen unless you explicitely enable it.
+By default, real networking mode is disabled.
+This basically means that real networking will not happen unless you explicitly enable it.
 
 This behaviour has been adopted to improve predictability, control and mitigate developers fear between
 behaviour boundaries and expectations.
 
-``pook`` will prevent you to communicate with real HTTP servers unless you enable it via: ``pook.enable_network()``.
+``pook`` will prevent you to communicate with real HTTP servers unless you enable it via: :func:`pook.enable_network`.
 
 Also, you can partially restrict the real networking by filtering only certain hosts.
-You can do that via ``pook.use_network_filter(filter_fn)``.
+You can do that via :func:`pook.use_network_filter`.
 
 
 Volatile vs Persistent mocks
@@ -53,7 +53,7 @@ and therefore consumed, it will be flushed.
 
 You can modify this behaviour via:
 
-Explicitly definining the TTL of each mock, so effectively the number of times the mock can be matched and consumed:
+Explicitly defining the TTL of each mock, so effectively the number of times the mock can be matched and consumed:
 
 .. code:: python
 
@@ -64,11 +64,11 @@ Explicitly definining the TTL of each mock, so effectively the number of times t
     pook.get('server.com/api', times=5)
 
 
-Explicitly definining a persistent mock:
+Explicitly defining a persistent mock:
 
 .. code:: python
 
-    # Make a mock definition persistent, so it won't be never flushed
+    # Make a mock definition persistent, so it won't ever be flushed
     pook.get('server.com/api').persist()
 
     # The above is equivalent to

docs/install.rst

@@ -4,18 +4,18 @@ Installation
 PyPI
 ----
 
-You can install the last stable release of Expects from PyPI using pip or easy_install::
+You can install the last stable release of pook from PyPI using pip::
 
     $ pip install pook
 
 GitHub
 ------
 
-Or install the latest sources from Github::
+Or install the latest sources from GitHub::
 
     $ pip install -e git+git://github.com/h2non/pook.git#egg=pook
 
-Also you can download a source code package from `Github <https://github.com/h2non/pook/tags>`_ and install it using setuptools::
+You can also download a source code package from `GitHub <https://github.com/h2non/pook/tags>`_ and install it using setuptools::
 
     $ tar xvf pook-{version}.tar.gz
     $ cd pook

pyproject.toml

@@ -52,7 +52,7 @@ packages = ["src/pook"]
 
 [tool.hatch.envs.default]
 python = "3.13"
-extra-dependencies = [
+dependencies = [
     "pre-commit~=4.0",
     "mypy>=1.11.2",
 
@@ -86,14 +86,14 @@ types = "mypy --install-types --non-interactive src/pook/interceptors {args}"
 
 [tool.hatch.envs.docs]
 extra-dependencies = [
-    "Sphinx~=7.2.6 ",
-    "sphinx-rtd-theme~=2.0.0",
+    "sphinx==8.1.3",
+    "sphinx-autobuild==2024.10.3",
+    "sphinx-rtd-theme==3.0.1",
 ]
 
 [tool.hatch.envs.docs.scripts]
-apidocs = "sphinx-apidoc -f --follow-links -H 'API documentation' -o docs/source src/pook"
-htmldocs = "rm -rf docs/_build && sphinx-build -b html -d docs/_build/doctrees ./docs docs/_build/html"
-build = "hatch run apidocs; hatch run htmldocs"
+preview = "sphinx-autobuild docs docs/_build/html {args}"
+build = "sphinx-build -b html docs docs/_build/html {args}"
 
 [tool.hatch.envs.test]
 [[tool.hatch.envs.test.matrix]]

src/pook/request.py

@@ -20,20 +20,13 @@ class Request:
         body (bytes|regex): request body payload to match.
         json (str|dict|list): JSON payload body structure to match.
         xml (str): XML payload data structure to match.
-
-    Attributes:
-        method (str): HTTP method to match. Defaults to ``GET``.
-        url (str): URL request to intercept and match.
-        headers (dict): HTTP headers to match.
-        query (dict): URL query params to match. Complementely to URL
-            defined query params.
-        body (bytes|regex): request body payload to match.
-        json (str|dict|list): JSON payload body structure to match.
-        xml (str): XML payload data structure to match.
     """
 
     # Store keys
     keys = ("method", "headers", "body", "url", "query", "xml", "json")
+    """
+    :meta private:
+    """
 
     def __init__(self, method="GET", **kw):
         self._url = None
@@ -47,6 +40,7 @@ def __init__(self, method="GET", **kw):
 
     @property
     def method(self):
+        """HTTP method to match. Defaults to ``GET``."""
         return self._method
 
     @method.setter
@@ -55,6 +49,7 @@ def method(self, method):
 
     @property
     def headers(self):
+        """HTTP headers to match."""
         return self._headers
 
     @headers.setter
@@ -75,6 +70,7 @@ def extra(self, extra):
 
     @property
     def url(self):
+        """URL request to intercept and match."""
         return self._url
 
     @url.setter
@@ -98,6 +94,7 @@ def rawurl(self):
 
     @property
     def query(self):
+        """URL query params to match. Complementary to URL defined query params."""
         return self._query
 
     @query.setter
@@ -106,6 +103,7 @@ def query(self, params):
 
     @property
     def body(self):
+        """request body payload to match."""
         return self._body
 
     @body.setter
@@ -117,6 +115,7 @@ def body(self, body):
 
     @property
     def json(self):
+        """JSON payload body structure to match."""
         return _json.loads(self.body.decode("utf-8"))
 
     @json.setter
@@ -128,6 +127,7 @@ def json(self, data):
 
     @property
     def xml(self):
+        """XML payload data structure to match."""
         return self.body.decode("utf-8")
 
     @xml.setter