Merge pull request #1659 from minrk/23-docs

Update docs for constant enums

Author: minrk

.pre-commit-config.yaml

@@ -1,9 +1,13 @@
 exclude: ^zmq/eventloop/minitornado/
 repos:
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v2.5.1
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.13  # Use the ref you want to point at
     hooks:
-      - id: prettier
+      - id: mdformat
+        # Optionally add plugins
+        additional_dependencies:
+          - mdformat-black
+          - mdformat-myst
   - repo: https://github.com/PyCQA/flake8
     rev: 4.0.1
     hooks:

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
@@ -48,7 +48,9 @@ For more detail on building pyzmq, see [our Wiki](https://github.com/zeromq/pyzm
 
 We build wheels for macOS, Windows, and Linux, so you can get a binary on those platforms with:
 
-    pip install pyzmq
+```
+pip install pyzmq
+```
 
 but compiling from source with `pip install pyzmq` should work in most environments.
 Especially on macOS, make sure you are using the latest pip (≥ 8), or it may not find the right wheels.
@@ -57,17 +59,21 @@ If the wheel doesn't work for some reason, or you want to force pyzmq to be comp
 (this is often preferable if you already have libzmq installed and configured the way you want it),
 you can force installation with:
 
-    pip install --no-binary=:all: pyzmq
+```
+pip install --no-binary=:all: pyzmq
+```
 
 When compiling pyzmq (e.g. installing with pip on Linux),
 it is generally recommended that zeromq be installed separately,
 via homebrew, apt, yum, etc:
 
-    # Debian-based
-    sudo apt-get install libzmq3-dev
+```
+# Debian-based
+sudo apt-get install libzmq3-dev
 
-    # RHEL-based
-    sudo yum install libzmq3-devel
+# RHEL-based
+sudo yum install libzmq3-devel
+```
 
 If this is not available, pyzmq will _try_ to build libzmq as a Python Extension,
 though this is not guaranteed to work.
@@ -79,9 +85,11 @@ Building pyzmq from the git repo (including release tags on GitHub) requires Cyt
 pyzmq 16 drops support Python 2.6 and 3.2.
 If you need to use one of those Python versions, you can pin your pyzmq version to before 16:
 
-    pip install 'pyzmq<16'
+```
+pip install 'pyzmq<16'
+```
 
-For libzmq 2.0.x, use 'pyzmq<2.1'
+For libzmq 2.0.x, use 'pyzmq\<2.1'
 
 pyzmq-2.1.11 was the last version of pyzmq to support Python 2.5,
 and pyzmq ≥ 2.2.0 requires Python ≥ 2.6.

docs/requirements.txt

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

docs/source/api/zmq.rst

@@ -88,6 +88,42 @@ Polling
 
 .. autofunction:: zmq.select
 
+Constants
+---------
+
+All libzmq constants are available as top-level attributes
+(``zmq.PUSH``, etc.),
+as well as via enums (``zmq.SocketType.PUSH``, etc.).
+
+.. versionchanged:: 23
+
+    constants for unavailable socket types
+    or draft features will always be defined in pyzmq,
+    whether the features themselves are available or not.
+
+.. versionadded:: 23
+
+    Each category of zmq constant is now available as an IntEnum.
+
+.. autoenum:: SocketType
+
+.. autoenum:: SocketOption
+
+.. autoenum:: Flag
+
+.. autoenum:: PollEvent
+
+.. autoenum:: ContextOption
+
+.. autoenum:: MessageOption
+
+.. autoenum:: Event
+
+.. autoenum:: SecurityMechanism
+
+.. autoenum:: DeviceType
+
+.. autoenum:: Errno
 
 Exceptions
 ----------