sphinx-related work (#554)

fixes #510

.github/workflows/docs.yaml

@@ -0,0 +1,32 @@
+name: docs
+
+on: ["push", "pull_request"]
+
+jobs:
+ docs:
+ # We want to run on external PRs, but not on our own internal PRs as they'll be run
+ # by the push to the branch.
+ if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+
+ runs-on: ubuntu-latest
+ steps:
+ - name: Setup Python
+ uses: actions/setup-python@v4
+ with:
+ python-version: '3.x'
+ architecture: 'x64'
+
+ - name: Checkout
+ uses: actions/checkout@v3
+
+ - name: Build
+ shell: bash
+ run: |
+ pip install -r requirements.txt
+ make cython
+ pip install .
+
+ - name: Sphinx Documentation Generator
+ run: |
+ pip install tox
+ tox -e sphinx

docs/_static/README.txt

@@ -0,0 +1 @@
+Sphinx will copy the contents of docs/_static/ directory to the build location.

docs/api.rst

@@ -5,19 +5,19 @@ API reference
 
 .. autofunction:: pack
 
-:func:`dump` is alias for :func:`pack`
+``dump()`` is an alias for :func:`pack`
 
 .. autofunction:: packb
 
-:func:`dumps` is alias for :func:`packb`
+``dumps()`` is an alias for :func:`packb`
 
 .. autofunction:: unpack
 
-:func:`load` is alias for :func:`unpack`
+``load()`` is an alias for :func:`unpack`
 
 .. autofunction:: unpackb
 
-:func:`loads` is alias for :func:`unpackb`
+``loads()`` is an alias for :func:`unpackb`
 
 .. autoclass:: Packer
  :members:

docs/conf.py

@@ -16,7 +16,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-# sys.path.insert(0, os.path.abspath('.'))
+#sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration -----------------------------------------------------
 

msgpack/_packer.pyx

@@ -71,7 +71,8 @@ cdef class Packer(object):
 
  Packer's constructor has some keyword arguments:
 
- :param callable default:
+ :param default:
+ When specified, it should be callable.
  Convert user type to builtin type that Packer supports.
  See also simplejson's document.
 

msgpack/_unpacker.pyx

@@ -217,7 +217,7 @@ cdef class Unpacker(object):
 
  :param file_like:
  File-like object having `.read(n)` method.
- If specified, unpacker reads serialized data from it and :meth:`feed()` is not usable.
+ If specified, unpacker reads serialized data from it and `.feed()` is not usable.
 
  :param int read_size:
  Used as `file_like.read(read_size)`. (default: `min(16*1024, max_buffer_size)`)
@@ -241,12 +241,12 @@ cdef class Unpacker(object):
  :param bool strict_map_key:
  If true (default), only str or bytes are accepted for map (dict) keys.
 
- :param callable object_hook:
+ :param object_hook:
  When specified, it should be callable.
  Unpacker calls it with a dict argument after unpacking msgpack map.
  (See also simplejson)
 
- :param callable object_pairs_hook:
+ :param object_pairs_hook:
  When specified, it should be callable.
  Unpacker calls it with a list of key-value pairs after unpacking msgpack map.
  (See also simplejson)

msgpack/ext.py

@@ -120,7 +120,7 @@ def from_unix(unix_sec):
  """Create a Timestamp from posix timestamp in seconds.
 
  :param unix_float: Posix timestamp in seconds.
- :type unix_float: int or float.
+ :type unix_float: int or float
  """
  seconds = int(unix_sec // 1)
  nanoseconds = int((unix_sec % 1) * 10**9)
@@ -154,7 +154,7 @@ def to_unix_nano(self):
  def to_datetime(self):
  """Get the timestamp as a UTC datetime.
 
- :rtype: datetime.
+ :rtype: `datetime.datetime`
  """
  utc = datetime.timezone.utc
  return datetime.datetime.fromtimestamp(0, utc) + datetime.timedelta(seconds=self.to_unix())

msgpack/fallback.py

@@ -139,7 +139,7 @@ class Unpacker:
 
  :param file_like:
  File-like object having `.read(n)` method.
- If specified, unpacker reads serialized data from it and :meth:`feed()` is not usable.
+ If specified, unpacker reads serialized data from it and `.feed()` is not usable.
 
  :param int read_size:
  Used as `file_like.read(read_size)`. (default: `min(16*1024, max_buffer_size)`)
@@ -163,12 +163,12 @@ class Unpacker:
  :param bool strict_map_key:
  If true (default), only str or bytes are accepted for map (dict) keys.
 
- :param callable object_hook:
+ :param object_hook:
  When specified, it should be callable.
  Unpacker calls it with a dict argument after unpacking msgpack map.
  (See also simplejson)
 
- :param callable object_pairs_hook:
+ :param object_pairs_hook:
  When specified, it should be callable.
  Unpacker calls it with a list of key-value pairs after unpacking msgpack map.
  (See also simplejson)
@@ -616,7 +616,8 @@ class Packer:
 
  Packer's constructor has some keyword arguments:
 
- :param callable default:
+ :param default:
+ When specified, it should be callable.
  Convert user type to builtin type that Packer supports.
  See also simplejson's document.
 

tox.ini

@@ -3,6 +3,7 @@ envlist =
  {py35,py36,py37,py38}-{c,pure},
  {pypy,pypy3}-pure,
  py34-x86,
+ sphinx,
 isolated_build = true
 
 [testenv]
@@ -27,3 +28,11 @@ commands=
  python -c 'import sys; print(hex(sys.maxsize))'
  python -c 'from msgpack import _cmsgpack'
  py.test
+
+
+[testenv:sphinx]
+changedir = docs
+deps =
+ sphinx
+commands =
+ sphinx-build -n -v -W --keep-going -b html -d {envtmpdir}/doctrees . {envtmpdir}/html