Split documentation into multiple sections
diff --git a/docs/conf.py b/docs/conf.py
index a300ad9..69a4d2a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -37,6 +37,7 @@
'sphinx.ext.intersphinx',
'sphinx.ext.inheritance_diagram',
'sphinx_autodoc_typehints',
+ 'sphinx.ext.autosectionlabel',
]
# Add any paths that contain templates here, relative to this directory.
@@ -196,43 +197,3 @@
'penwidth': 1.2,
'arrowsize': 0.8,
}
-
-
-###################################################################################################
-
-
-from sphinx.ext.autosummary import Autosummary
-from sphinx.ext.autosummary import get_documenter
-from sphinx.util.inspect import safe_getattr
-
-
-class AutoAutoSummary(Autosummary):
- option_spec = {}
-
- required_arguments = 1
-
- @staticmethod
- def get_members(obj):
- for name in dir(obj):
- try:
- documenter = get_documenter(safe_getattr(obj, name), obj)
- except AttributeError:
- continue
-
- if documenter.objtype in ('function',):
- yield name
-
- def run(self):
- module = str(self.arguments[0])
- try:
- m = __import__(module, globals(), locals(), [])
- self.content = sorted(
- ('~%s.%s' % (module, member) for member in self.get_members(m)),
- key=str.lower,
- )
- finally:
- return super().run()
-
-
-def setup(app):
- app.add_directive('autoautosummary', AutoAutoSummary)
diff --git a/docs/decoder.rst b/docs/decoder.rst
new file mode 100644
index 0000000..3cda80f
--- /dev/null
+++ b/docs/decoder.rst
@@ -0,0 +1,81 @@
+Parser / Decoder
+================
+
+All valid `JSON5 1.0.0 <https://spec.json5.org/>`_ and
+`JSON <https://tools.ietf.org/html/rfc8259>`_ data can be read,
+unless the nesting level is absurdly high.
+
+
+Quick Decoder Summary
+---------------------
+
+.. autosummary::
+
+ ~pyjson5.decode
+ ~pyjson5.decode_buffer
+ ~pyjson5.decode_callback
+ ~pyjson5.decode_io
+ ~pyjson5.load
+ ~pyjson5.loads
+ ~pyjson5.Json5DecoderException
+ ~pyjson5.Json5NestingTooDeep
+ ~pyjson5.Json5EOF
+ ~pyjson5.Json5IllegalCharacter
+ ~pyjson5.Json5ExtraData
+ ~pyjson5.Json5IllegalType
+
+
+Full Decoder Description
+------------------------
+
+.. autofunction:: pyjson5.decode
+
+.. autofunction:: pyjson5.decode_buffer
+
+.. autofunction:: pyjson5.decode_callback
+
+.. autofunction:: pyjson5.decode_io
+
+
+Decoder Compatibility Functions
+-------------------------------
+
+.. autofunction:: pyjson5.load
+
+.. autofunction:: pyjson5.loads
+
+
+Decoder Exceptions
+------------------
+
+.. inheritance-diagram::
+ pyjson5.Json5DecoderException
+ pyjson5.Json5NestingTooDeep
+ pyjson5.Json5EOF
+ pyjson5.Json5IllegalCharacter
+ pyjson5.Json5ExtraData
+ pyjson5.Json5IllegalType
+
+.. autoclass:: pyjson5.Json5DecoderException
+ :members:
+ :inherited-members:
+
+.. autoclass:: pyjson5.Json5NestingTooDeep
+ :members:
+ :inherited-members:
+
+.. autoclass:: pyjson5.Json5EOF
+ :members:
+ :inherited-members:
+
+.. autoclass:: pyjson5.Json5IllegalCharacter
+ :members:
+ :inherited-members:
+
+.. autoclass:: pyjson5.Json5ExtraData
+ :members:
+ :inherited-members:
+
+.. autoclass:: pyjson5.Json5IllegalType
+ :members:
+ :inherited-members:
diff --git a/docs/encoder.rst b/docs/encoder.rst
new file mode 100644
index 0000000..4ca15a3
--- /dev/null
+++ b/docs/encoder.rst
@@ -0,0 +1,73 @@
+Serializer / Encoder
+====================
+
+The serializer returns ASCII data that can safely be used in an HTML template.
+Apostrophes, ampersands, greater-than, and less-then signs are encoded as
+unicode escaped sequences. E.g. this snippet is safe for any and all input:
+
+.. code:: html
+
+ "<a onclick='alert(" + encode(data) + ")'>show message</a>"
+
+Unless the input contains infinite or NaN values, the result will be valid
+`JSON <https://tools.ietf.org/html/rfc8259>`_ data.
+
+
+Quick Encoder Summary
+---------------------
+
+.. autosummary::
+
+ ~pyjson5.encode
+ ~pyjson5.encode_bytes
+ ~pyjson5.encode_callback
+ ~pyjson5.encode_io
+ ~pyjson5.encode_noop
+ ~pyjson5.dump
+ ~pyjson5.dumps
+ ~pyjson5.Options
+ ~pyjson5.Json5EncoderException
+ ~pyjson5.Json5UnstringifiableType
+
+
+Full Encoder Description
+------------------------
+
+.. autofunction:: pyjson5.encode
+
+.. autofunction:: pyjson5.encode_bytes
+
+.. autofunction:: pyjson5.encode_callback
+
+.. autofunction:: pyjson5.encode_io
+
+.. autofunction:: pyjson5.encode_noop
+
+.. autoclass:: pyjson5.Options
+ :members:
+ :inherited-members:
+
+
+Encoder Compatibility Functions
+-------------------------------
+
+.. autofunction:: pyjson5.dump
+
+.. autofunction:: pyjson5.dumps
+
+
+Encoder Exceptions
+------------------
+
+.. inheritance-diagram::
+ pyjson5.Json5Exception
+ pyjson5.Json5EncoderException
+ pyjson5.Json5UnstringifiableType
+
+.. autoclass:: pyjson5.Json5EncoderException
+ :members:
+ :inherited-members:
+
+.. autoclass:: pyjson5.Json5UnstringifiableType
+ :members:
+ :inherited-members:
diff --git a/docs/exceptions.rst b/docs/exceptions.rst
new file mode 100644
index 0000000..21b9f34
--- /dev/null
+++ b/docs/exceptions.rst
@@ -0,0 +1,17 @@
+Exceptions
+==========
+
+.. inheritance-diagram::
+ pyjson5.Json5Exception
+ pyjson5.Json5EncoderException
+ pyjson5.Json5UnstringifiableType
+ pyjson5.Json5DecoderException
+ pyjson5.Json5NestingTooDeep
+ pyjson5.Json5EOF
+ pyjson5.Json5IllegalCharacter
+ pyjson5.Json5ExtraData
+ pyjson5.Json5IllegalType
+
+.. autoclass:: pyjson5.Json5Exception
+ :members:
+ :inherited-members:
diff --git a/docs/index.rst b/docs/index.rst
index 91472f0..6f09e82 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,21 +1,76 @@
-.. currentmodule:: pyjson5
+PyJSON5
+=======
-.. automodule:: pyjson5
- :members:
- :inherited-members:
+A JSON5 serializer and parser library for Python 3.4 and later.
- → :ref:`Glossary / Index <genindex>`
+The serializer returns ASCII data that can safely be used in an HTML template.
+Apostrophes, ampersands, greater-than, and less-then signs are encoded as
+unicode escaped sequences. E.g. this snippet is safe for any and all input:
- Function summary
- ----------------
+.. code:: html
- .. autoautosummary:: pyjson5
+ "<a onclick='alert(" + encode(data) + ")'>show message</a>"
- Class / exception summary
- -------------------------
+Unless the input contains infinite or NaN values, the result will be valid
+`JSON <https://tools.ietf.org/html/rfc8259>`_ data.
- .. inheritance-diagram:: pyjson5
- Full description
- ----------------
+All valid `JSON5 1.0.0 <https://spec.json5.org/>`_ and
+`JSON <https://tools.ietf.org/html/rfc8259>`_ data can be read,
+unless the nesting level is absurdly high.
+
+
+Installation
+------------
+
+.. code:: bash
+
+ $ pip install pyjson5
+
+
+Table of Contents
+-----------------
+
+.. toctree::
+ :maxdepth: 3
+
+ encoder.rst
+ decoder.rst
+ exceptions.rst
+
+
+Quick Summary
+-------------
+
+.. autosummary::
+
+ ~pyjson5.decode
+ ~pyjson5.decode_buffer
+ ~pyjson5.decode_callback
+ ~pyjson5.decode_io
+ ~pyjson5.load
+ ~pyjson5.loads
+ ~pyjson5.encode
+ ~pyjson5.encode_bytes
+ ~pyjson5.encode_callback
+ ~pyjson5.encode_io
+ ~pyjson5.encode_noop
+ ~pyjson5.dump
+ ~pyjson5.dumps
+ ~pyjson5.Options
+ ~pyjson5.Json5EncoderException
+ ~pyjson5.Json5DecoderException
+
+
+Compatibility
+-------------
+
+At least CPython 3.4, and a C++14 compatible compiler (such as GCC 5.2+) is needed.
+
+Other interpreters such as Pypy and older CPython versions are not supported.
+
+
+-------------------------------------------------------------------------------
+
+:ref:`Glossary / Index <genindex>`
diff --git a/src/DESCRIPTION b/src/DESCRIPTION
index 43f722d..266d20f 100644
--- a/src/DESCRIPTION
+++ b/src/DESCRIPTION
@@ -1,6 +1,6 @@
'''\
PyJSON5
--------
+=======
A `JSON5 <https://spec.json5.org/>`_ serializer and parser library for Python 3 written in Cython.
