Convert RST docs to markdown

docs/abc.rst → docs/abc.md

@@ -1,5 +1,6 @@
-Codec API
-=========
+# Codec API
+
+```{eval-rst}
 .. automodule:: numcodecs.abc
 
 .. autoclass:: Codec
@@ -9,3 +10,4 @@ Codec API
     .. automethod:: decode
     .. automethod:: get_config
     .. automethod:: from_config
+```

docs/api.md

@@ -0,0 +1,13 @@
+# API reference
+
+```{toctree}
+:maxdepth: 2
+
+compression/index
+filter/index
+other/index
+checksum32
+abc
+registry
+zarr3
+```

docs/checksum32.rst → docs/checksum32.md

@@ -1,56 +1,63 @@
-Checksum codecs
-===============
+# Checksum codecs
+
+```{eval-rst}
 .. automodule:: numcodecs.checksum32
+```
+
+## CRC32
 
-CRC32
------
+```{eval-rst}
 .. autoclass:: CRC32
 
     .. autoattribute:: codec_id
     .. automethod:: encode
     .. automethod:: decode
     .. automethod:: get_config
     .. automethod:: from_config
+```
 
+## CRC32C
 
-CRC32C
-------
+```{eval-rst}
 .. autoclass:: CRC32C
 
     .. autoattribute:: codec_id
     .. automethod:: encode
     .. automethod:: decode
     .. automethod:: get_config
     .. automethod:: from_config
+```
 
+## Adler32
 
-Adler32
--------
+```{eval-rst}
 .. autoclass:: Adler32
 
     .. autoattribute:: codec_id
     .. automethod:: encode
     .. automethod:: decode
     .. automethod:: get_config
     .. automethod:: from_config
+```
 
+## Fletcher32
 
-Fletcher32
-----------
-
+```{eval-rst}
 .. autoclass:: numcodecs.fletcher32.Fletcher32
 
     .. autoattribute:: codec_id
     .. automethod:: encode
     .. automethod:: decode
+```
 
-JenkinsLookup3
---------------
+## JenkinsLookup3
 
+```{eval-rst}
 .. autoclass:: JenkinsLookup3
 
     .. autoattribute:: codec_id
     .. autoattribute:: initval
     .. autoattribute:: prefix
     .. automethod:: encode
     .. automethod:: decode
+```

docs/compression/blosc.rst → docs/compression/blosc.md

@@ -1,5 +1,6 @@
-Blosc
-=====
+# Blosc
+
+```{eval-rst}
 .. automodule:: numcodecs.blosc
 
 .. autoclass:: Blosc
@@ -14,13 +15,15 @@ Blosc
     .. automethod:: get_config
     .. automethod:: from_config
     .. automethod:: decode_partial
+```
 
-Helper functions
-----------------
+## Helper functions
 
+```{eval-rst}
 .. autofunction:: list_compressors
 .. autofunction:: get_nthreads
 .. autofunction:: set_nthreads
 .. autofunction:: cbuffer_complib
 .. autofunction:: compress
 .. autofunction:: decompress
+```

docs/compression/bz2.rst → docs/compression/bz2.md

@@ -1,5 +1,6 @@
-BZ2
-===
+# BZ2
+
+```{eval-rst}
 .. automodule:: numcodecs.bz2
 
 .. autoclass:: BZ2
@@ -9,3 +10,4 @@ BZ2
     .. automethod:: decode
     .. automethod:: get_config
     .. automethod:: from_config
+```

docs/compression/gzip.rst → docs/compression/gzip.md

@@ -1,5 +1,6 @@
-GZip
-====
+# GZip
+
+```{eval-rst}
 .. automodule:: numcodecs.gzip
 
 .. autoclass:: GZip
@@ -9,3 +10,4 @@ GZip
     .. automethod:: decode
     .. automethod:: get_config
     .. automethod:: from_config
+```

docs/compression/index.md

@@ -0,0 +1,15 @@
+# Compression codecs
+
+```{toctree}
+:maxdepth: 2
+
+blosc
+bz2
+gzip
+lzma
+lz4
+pcodec
+zfpy
+zlib
+zstd
+```

docs/compression/lz4.rst → docs/compression/lz4.md

@@ -1,5 +1,6 @@
-LZ4
-===
+# LZ4
+
+```{eval-rst}
 .. automodule:: numcodecs.lz4
 
 .. autoclass:: LZ4
@@ -9,9 +10,11 @@ LZ4
     .. automethod:: decode
     .. automethod:: get_config
     .. automethod:: from_config
+```
 
-Helper functions
-----------------
+## Helper functions
 
+```{eval-rst}
 .. autofunction:: compress
 .. autofunction:: decompress
+```

docs/compression/lzma.rst → docs/compression/lzma.md

@@ -1,5 +1,6 @@
-LZMA
-====
+# LZMA
+
+```{eval-rst}
 .. automodule:: numcodecs.lzma
 
 .. autoclass:: LZMA
@@ -9,3 +10,4 @@ LZMA
     .. automethod:: decode
     .. automethod:: get_config
     .. automethod:: from_config
+```

docs/compression/pcodec.rst → docs/compression/pcodec.md

@@ -1,10 +1,11 @@
-PCodec
-======
+# PCodec
 
+```{eval-rst}
 .. automodule:: numcodecs.pcodec
 
 .. autoclass:: PCodec
 
     .. autoattribute:: codec_id
     .. automethod:: encode
     .. automethod:: decode
+```

docs/compression/zfpy.rst → docs/compression/zfpy.md

@@ -1,5 +1,6 @@
-ZFPY
-====
+# ZFPY
+
+```{eval-rst}
 .. automodule:: numcodecs.zfpy
 
 .. autoclass:: ZFPY
@@ -9,3 +10,4 @@ ZFPY
     .. automethod:: decode
     .. automethod:: get_config
     .. automethod:: from_config
+```

docs/compression/zlib.rst → docs/compression/zlib.md

@@ -1,5 +1,6 @@
-Zlib
-====
+# Zlib
+
+```{eval-rst}
 .. automodule:: numcodecs.zlib
 
 .. autoclass:: Zlib
@@ -9,3 +10,4 @@ Zlib
     .. automethod:: decode
     .. automethod:: get_config
     .. automethod:: from_config
+```

docs/compression/zstd.rst → docs/compression/zstd.md

@@ -1,20 +1,25 @@
-Zstd
-====
+# Zstd
+
+```{eval-rst}
 .. automodule:: numcodecs.zstd
 
 .. autoclass:: Zstd
 
     .. autoattribute:: codec_id
     .. automethod:: encode
     .. automethod:: decode
-        .. note::
-            If the compressed data does not contain the decompressed size, streaming
-            decompression will be used.
+
+    .. note::
+        If the compressed data does not contain the decompressed size, streaming
+        decompression will be used.
+
     .. automethod:: get_config
     .. automethod:: from_config
+```
 
-Helper functions
-----------------
+## Helper functions
 
+```{eval-rst}
 .. autofunction:: compress
 .. autofunction:: decompress
+```

docs/conf.py

@@ -49,6 +49,7 @@ def __getattr__(cls, name):
     'sphinx.ext.viewcode',
     'numpydoc',
     'sphinx_issues',
+    'myst_parser',
 ]
 
 numpydoc_show_class_members = False
@@ -59,9 +60,10 @@ def __getattr__(cls, name):
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -129,6 +131,13 @@ def __getattr__(cls, name):
 todo_include_todos = False
 
 
+# -- Options for MyST -------------------------------------------------------
+
+myst_enable_extensions = [
+    "colon_fence",
+]
+
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for