Merge pull request #7 from swordapp/docs-updates

Docs: API reference and intersphinx

docs/api.rst

@@ -1,5 +1,37 @@
 API Reference
 =============
 
+SWORD document types
+--------------------
+
 .. automodule:: sword3common
-   :members:
+   :members:
+
+
+Exceptions
+----------
+
+.. automodule:: sword3common.exceptions
+   :members:
+
+
+Constants
+---------
+
+.. module:: sword3common.constants
+
+
+JSON-LD context
+~~~~~~~~~~~~~~~
+
+
+.. autodata:: JSON_LD_CONTEXT
+
+Packaging formats
+~~~~~~~~~~~~~~~~~
+
+.. autodata:: PACKAGE_BINARY
+
+.. autodata:: PACKAGE_SWORDBAGIT
+
+.. autodata:: PACKAGE_SIMPLEZIP

docs/conf.py

@@ -32,6 +32,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
     'sphinx_autodoc_annotation',
 ]
 
@@ -57,3 +58,8 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+
+# -- Options for Intersphinx
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

docs/index.rst

@@ -2,6 +2,7 @@
    sphinx-quickstart on Thu Jul 16 13:16:05 2020.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
+
 Welcome to SWORDv3 common library's documentation!
 ==================================================
 
@@ -18,4 +19,4 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+* :ref:`search`

sword3common/__init__.py

@@ -19,4 +19,9 @@
     "Error",
 ]
 
+# Make this module the canonical import location for these members.
+# This will provide shorter class path/names in the documentation.
+for name in __all__:
+    locals()[name].__module__ = __name__
+
 from .version import __version__

sword3common/constants.py

@@ -1,3 +1,4 @@
+#: The JSON-LD context for the SWORDv3 protocol
 JSON_LD_CONTEXT = "https://swordapp.github.io/swordv3/swordv3.jsonld"
 
 DISPOSITION_SEGMENT_INIT = "disposition_segment_init"
@@ -19,9 +20,12 @@
 
 URI_METADATA = "http://purl.org/net/sword/3.0/types/Metadata"
 
+#: The URI for the `Binary <https://swordapp.github.io/swordv3/swordv3.html#22.1>`_ packaging format
 PACKAGE_BINARY = "http://purl.org/net/sword/3.0/package/Binary"
-PACKAGE_SWORDBAGIT = "http://purl.org/net/sword/3.0/package/SWORDBagIt"
+#: The URI for the `SimpleZip <https://swordapp.github.io/swordv3/swordv3.html#22.2>`_ packaging format
 PACKAGE_SIMPLEZIP = "http://purl.org/net/sword/3.0/package/SimpleZip"
+#: The URI for the `SWORDBagIt <https://swordapp.github.io/swordv3/swordv3.html#22.3>`_ packaging format
+PACKAGE_SWORDBAGIT = "http://purl.org/net/sword/3.0/package/SWORDBagIt"
 
 CREATED = 201
 ACCEPTED = 202

sword3common/exceptions.py

@@ -14,11 +14,12 @@ def __new__(mcs, name, bases, attrs):
         cls = super().__new__(mcs, name, bases, attrs)
         if hasattr(cls, "status_code") and hasattr(cls, "name"):
             cls._registry[(cls.status_code, cls.name)] = cls
+        if getattr(cls, "reason", None):
+            cls.__doc__ = cls.reason
         return cls
 
 
 class SwordException(Exception, metaclass=SwordExceptionMeta):
-
     status_code = None  #: int
     name = None  #: str
     reason = None  #: str