adopt pydata-sphinx-theme

move howto docs into subfolder

Author: minrk

AUTHORS.md

@@ -92,7 +92,9 @@ The following people have contributed to the project:
 
 as reported by:
 
-    git log --all --format='- %aN (%aE)' | sort -u | sed 's/@/ AT /1' | sed -e 's/\.\([^ ]\)/ DOT \1/g'
+```
+git log --all --format='- %aN (%aE)' | sort -u | sed 's/@/ AT /1' | sed -e 's/\.\([^ ]\)/ DOT \1/g'
+```
 
 with some adjustments.
 

CONTRIBUTING.md

@@ -2,13 +2,13 @@
 
 For a good bug report:
 
-1. [Search][] for existing Issues, both on GitHub and in general with Google/Stack Overflow before posting a duplicate question.
-2. Update to pyzmq master, if possible, especially if you are already using git. It's
+1. [Search] for existing Issues, both on GitHub and in general with Google/Stack Overflow before posting a duplicate question.
+1. Update to pyzmq master, if possible, especially if you are already using git. It's
    possible that the bug you are about to report has already been fixed.
 
 Many things reported as pyzmq Issues are often just libzmq-related,
 and don't have anything to do with pyzmq itself.
-These are better directed to [zeromq-dev][].
+These are better directed to [zeromq-dev].
 
 When making a bug report, it is helpful to tell us as much as you can about your system
 (such as pyzmq version, libzmq version, Python version, OS Version, how you built/installed pyzmq and libzmq, etc.)
@@ -26,13 +26,12 @@ print("Python-%s" % sys.version)
 
 Which will give something like:
 
-    libzmq-3.3.0
-    pyzmq-2.2dev
-    Python-2.7.2 (default, Jun 20 2012, 16:23:33)
-    [GCC 4.2.1 Compatible Apple Clang 4.0 (tags/Apple/clang-418.0.60)]
-
-[search]: https://github.com/zeromq/pyzmq/issues
-[zeromq-dev]: mailto:[email protected]
+```
+libzmq-4.3.4
+pyzmq-22.3.0
+Python-3.9.9 | packaged by conda-forge | (main, Dec 20 2021, 02:38:53)
+[Clang 11.1.0 ]
+```
 
 # Licensing and contributing to PyZMQ
 
@@ -58,28 +57,35 @@ When you contribute to PyZMQ, your contributions are made under the same
 license as the file you are working on. Any new, original code should be BSD
 licensed.
 
-We don't enforce strict style, but when in doubt [PEP8][] is a good guideline.
-The only thing we really don't like is mixing up 'cleanup' in real work.
+We use [pre-commit] for autoformatting,
+so you hopefully don't need to worry too much about style.
 
-Examples are copyright their respective authors, and BSD unless otherwise
-specified by the author. You can LGPL (or GPL or MIT or Apache, etc.) your own new
-examples if you like, but we strongly encourage using the default BSD license.
+To install pre-commit:
+
+```
+pip install pre-commit
+pre-commit install
+```
 
-[pep8]: http://www.python.org/dev/peps/pep-0008
+Examples are copyright their respective authors, and BSD unless otherwise
+specified by the author.
 
 ## Inherited licenses in pyzmq
 
 Some code outside the core is taken from other open-source projects, and
 inherits that project's license.
 
-- zmq/eventloop contains files inherited and adapted from [tornado][], and inherits the Apache license
+- zmq/eventloop contains files inherited and adapted from [tornado], and inherits the Apache license
 
-- zmq/ssh/forward.py is from [paramiko][], and inherits LGPL
+- zmq/ssh/forward.py is from [paramiko], and inherits LGPL
 
 - zmq/devices/monitoredqueue.pxd is derived from the zmq_device function in
   libzmq, and inherits LGPL
 
 - perf examples are (c) iMatix, and LGPL
 
-[tornado]: http://www.tornadoweb.org
 [paramiko]: http://www.lag.net/paramiko
+[pre-commit]: https://pre-commit.com
+[search]: https://github.com/zeromq/pyzmq/issues
+[tornado]: http://www.tornadoweb.org
+[zeromq-dev]: mailto:[email protected]

README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://github.com/zeromq/pyzmq/actions/workflows/test.yml/badge.svg)](https://github.com/zeromq/pyzmq/actions/workflows/test.yml)
 
-This package contains Python bindings for [ØMQ](http://www.zeromq.org).
+This package contains Python bindings for [ØMQ](https://zeromq.org).
 ØMQ is a lightweight and fast messaging implementation.
 
 PyZMQ should work with any reasonable version of Python (≥ 3.4),
@@ -36,7 +36,7 @@ Python version of every example. We also have some information on our
 
 Unless you specifically want to develop PyZMQ, we recommend downloading
 the PyZMQ source code or wheels from
-[PyPI](https://pypi.io/project/pyzmq),
+[PyPI](https://pypi.io/project/pyzmq/),
 or install with conda.
 
 You can also get the latest source code from our GitHub repository, but

docs/requirements.txt

@@ -2,6 +2,7 @@ cython>=0.29
 enum-tools[sphinx]>=0.9
 gevent
 myst-parser[linkify]
+pydata_sphinx_theme
 pygments>=2.6
 sphinx>=3.0.4
 sphinx-rtd-theme==0.5.*

docs/source/changelog.md

@@ -225,7 +225,7 @@ Fixes:
 - Cython backend: Build Cython extensions with language level "3str" (requires Cython 0.29)
 - Cython backend: You can now `cimport zmq`
 - Asyncio: Fix memory leak in Poller
-- Log: Much improved logging in {mod}`zmq.log` (see {doc}`logging`)
+- Log: Much improved logging in {mod}`zmq.log` (see {doc}`howto/logging`)
 - Log: add `python -m zmq.log` entrypoint
 - Sources generated with Cython 0.29.15
 

docs/source/conf.py

@@ -122,8 +122,20 @@
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'sphinx_rtd_theme'
-
+html_theme = "pydata_sphinx_theme"
+
+# html_logo = "_static/logo.png"
+
+html_theme_options = {
+    "icon_links": [
+        {
+            # Label for this link
+            "name": "PyZMQ on GitHub",
+            "url": "https://github.com/zeromq/pyzmq",
+            "icon": "fab fa-github-square",
+        }
+    ]
+}
 # 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
 # documentation.

docs/source/devices.md renamed to docs/source/howto/devices.md

@@ -0,0 +1,14 @@
+# Using PyZMQ
+
+```{toctree}
+---
+maxdepth: 2
+---
+morethanbindings.rst
+serialization.rst
+devices.rst
+eventloop.rst
+draft.rst
+logging.rst
+ssh.rst
+```