Merge pull request #1958 from minrk/docbuild

lots of small doc fixes

.github/workflows/test-docs.yml

@@ -0,0 +1,60 @@
+name: Test docs
+
+# The tests defined in docs/ are currently influenced by changes to _version.py
+# and scopes.py.
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "zmq/**"
+      - ".github/workflows/test-docs.yml"
+  push:
+    paths:
+      - "docs/**"
+      - "zmq/**"
+      - ".github/workflows/test-docs.yml"
+    branches-ignore:
+      - "dependabot/**"
+      - "pre-commit-ci-update-config"
+    tags:
+      - "**"
+  workflow_dispatch:
+
+env:
+  LANG: C.UTF-8
+  SPHINXOPTS: "-W"
+
+jobs:
+  test-docs:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install libzmq
+        run: |
+          sudo apt-get -y install libzmq3-dev
+
+      - name: Install pyzmq
+        run: |
+          pip install -v .
+
+      - name: Install requirements
+        run: |
+          pip install -r docs/requirements.txt
+
+      # readthedocs doesn't halt on warnings,
+      # so raise any warnings here
+      - name: build docs
+        run: |
+          cd docs
+          make html
+
+      - name: check links
+        run: |
+          cd docs
+          make linkcheck

.github/workflows/test.yml

@@ -8,12 +8,14 @@ on:
     paths-ignore:
       - "docs/**"
       - "tools/**"
-      - .github/workflows/wheels.yml
+      - ".github/workflows/*"
+      - "!.github/workflows/test.yml"
   pull_request:
     paths-ignore:
       - "docs/**"
       - "tools/**"
-      - .github/workflows/wheels.yml
+      - ".github/workflows/*"
+      - "!.github/workflows/test.yml"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

buildutils/constants.py

@@ -79,7 +79,7 @@ def promoted_constants():
             raise ValueError("Never encountered AUTOGENERATED_BELOW_HERE")
 
     global_assignments = []
-    all_lines = ["__all__: List[str] = ["]
+    all_lines = ["__all__: list[str] = ["]
     for cls_name in sorted(dir(constants)):
         if cls_name.startswith("_"):
             continue

docs/Makefile

@@ -2,11 +2,11 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = build
-SRCDIR        = source
+SPHINXOPTS    ?= -n
+SPHINXBUILD   ?= sphinx-build
+PAPER         ?=
+BUILDDIR      ?= build
+SRCDIR        ?= source
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4

docs/source/api/index.md

@@ -0,0 +1,29 @@
+---
+Date: '{{ today }}'
+Release: '{{ release }}'
+---
+
+(api-index)=
+
+# The PyZMQ API
+
+```{toctree}
+zmq
+zmq.devices
+zmq.decorators
+zmq.green
+zmq.eventloop.ioloop
+zmq.eventloop.future
+zmq.asyncio
+zmq.eventloop.zmqstream
+zmq.auth
+zmq.auth.asyncio
+zmq.auth.thread
+zmq.auth.ioloop
+zmq.log.handlers
+zmq.ssh.tunnel
+zmq.utils.jsonapi
+zmq.utils.monitor
+zmq.utils.z85
+zmq.utils.win32
+```

docs/source/api/zmq.asyncio.md

@@ -0,0 +1,88 @@
+# asyncio
+
+## Module: {mod}`zmq.asyncio`
+
+```{eval-rst}
+.. automodule:: zmq.asyncio
+```
+
+```{currentmodule} zmq.asyncio
+```
+
+```{versionadded} 15.0
+```
+
+As of 15.0, pyzmq now supports {mod}`asyncio`, via {mod}`zmq.asyncio`.
+When imported from this module, blocking methods such as
+{meth}`Socket.recv_multipart`, {meth}`Socket.poll`,
+and {meth}`Poller.poll` return {class}`~.asyncio.Future` s.
+
+```python
+import asyncio
+import zmq
+import zmq.asyncio
+
+ctx = zmq.asyncio.Context()
+
+
+async def recv_and_process():
+    sock = ctx.socket(zmq.PULL)
+    sock.bind(url)
+    msg = await sock.recv_multipart()  # waits for msg to be ready
+    reply = await async_process(msg)
+    await sock.send_multipart(reply)
+
+
+asyncio.run(recv_and_process())
+```
+
+## Classes
+
+### {class}`Context`
+
+Context class that creates Future-returning sockets. See {class}`zmq.Context` for more info.
+
+```{eval-rst}
+.. autoclass:: Context
+
+
+```
+
+### {class}`Socket`
+
+Socket subclass that returns {class}`asyncio.Future` s from blocking methods,
+for use in coroutines and async applications.
+
+```{seealso}
+{class}`zmq.Socket` for the inherited API.
+```
+
+```{eval-rst}
+.. autoclass:: Socket
+
+  .. automethod:: recv
+
+  .. automethod:: recv_multipart
+
+  .. automethod:: send
+
+  .. automethod:: send_multipart
+
+  .. automethod:: poll
+
+```
+
+### {class}`Poller`
+
+Poller subclass that returns {class}`asyncio.Future` s from poll,
+for use in coroutines and async applications.
+
+```{seealso}
+{class}`zmq.Poller` for the inherited API.
+```
+
+```{eval-rst}
+.. autoclass:: Poller
+
+  .. automethod:: poll
+```