Merge pull request #45 from laws-africa/docs

Bring docs up to date

README.rst

@@ -13,7 +13,7 @@ It makes it easy to work with Akoma Ntoso metadata, FRBR URIs and generate Table
 It is lightweight because most operations are done on the XML document directly without intermediate
 objects. You still need to understand how Akoma Ntoso works.
 
-Read the `full documentation at cobalt.readthedocs.org <http://cobalt.readthedocs.org/en/latest/>`_.
+Read the `full documentation at cobalt.readthedocs.io <http://cobalt.readthedocs.io/en/latest/>`_.
 
 Quickstart
 ----------

cobalt/__init__.py

@@ -8,14 +8,16 @@
 from .portion import PortionStructure, Portion
 from .uri import FrbrUri
 
-__all__ = [Act, AkomaNtosoDocument, Amendment, AmendmentEvent, AmendmentList, AmendmentStructure,
-           Bill,
-           Collection, CollectionStructure,
-           DebateRecord, DebateReport, DebateStructure, Document, datestring,
-           FrbrUri,
-           HierarchicalStructure,
-           Judgment, JudgmentStructure,
-           OfficialGazette, OpenStructure,
-           Portion, PortionStructure,
-           RepealEvent,
-           Statement, StructuredDocument]
+__all__ = [
+    'Act', 'AkomaNtosoDocument', 'Amendment', 'AmendmentEvent', 'AmendmentList', 'AmendmentStructure',
+    'Bill',
+    'Collection', 'CollectionStructure',
+    'DebateRecord', 'DebateReport', 'DebateStructure', 'Document', 'datestring',
+    'FrbrUri',
+    'HierarchicalStructure',
+    'Judgment', 'JudgmentStructure',
+    'OfficialGazette', 'OpenStructure',
+    'Portion', 'PortionStructure',
+    'RepealEvent',
+    'Statement', 'StructuredDocument',
+]

cobalt/akn.py

@@ -46,6 +46,9 @@ def get_maker(version=DEFAULT_VERSION):
 
 class AkomaNtosoDocument:
     """ Base class for Akoma Ntoso documents.
+
+    :ivar root: :class:`lxml.objectify.ObjectifiedElement` root of the XML document
+    :ivar namespace: primary XML namespace
     """
     _parser = objectify_parser
 
@@ -264,7 +267,7 @@ def parse(self, xml, document_type=None):
 
     @property
     def main(self):
-        """ Get the root document element.
+        """ Get the main document element (normally the first child of the root element).
         """
         return getattr(self.root, self.document_type)
 
@@ -332,7 +335,8 @@ def manifestation_date(self, value):
 
     @property
     def language(self):
-        """ The 3-letter ISO-639-2 language code of this document """
+        """ The 3-letter ISO-639-2 language code of this document.
+        """
         return self.meta.identification.FRBRExpression.FRBRlanguage.get('language', 'eng')
 
     @language.setter
@@ -343,7 +347,8 @@ def language(self, value):
 
     @property
     def frbr_uri(self):
-        """ The FRBR Manifestation URI as a :class:`FrbrUri` instance that uniquely identifies this document universally. """
+        """ The FRBR Manifestation URI as a :class:`cobalt.uri.FrbrUri` instance that uniquely identifies this document universally.
+        """
         uri = self.meta.identification.FRBRManifestation.FRBRuri.get('value')
         if uri:
             return FrbrUri.parse(uri)
@@ -390,7 +395,9 @@ def frbr_uri(self, uri):
             ident.FRBRManifestation.FRBRthis.set('value', uri.expression_uri())
 
     def expression_frbr_uri(self):
-        """ The FRBR Expression URI as a :class:`FrbrUri` instance that uniquely identifies this document universally. """
+        """ The FRBR Expression URI as a :class:`cobalt.uri.FrbrUri` instance that uniquely identifies this document
+        universally.
+        """
         uri = self.meta.identification.FRBRExpression.FRBRuri.get('value')
         if uri:
             return FrbrUri.parse(uri)

cobalt/hierarchical.py

@@ -10,18 +10,7 @@ class HierarchicalStructure(StructuredDocument):
 
 class Act(HierarchicalStructure):
     """
-    An act is a lightweight wrapper around an `Akoma Ntoso 2.0 XML <http://www.akomantoso.org/>`_ act document.
-    It provides methods to help access and manipulate the underlying XML directly, in particular
-    the metadata for the document.
-
-    The Act object provides quick access to certain sections of the document:
-
-    :ivar root: :class:`lxml.objectify.ObjectifiedElement` root of the XML document
-    :ivar meta: :class:`lxml.objectify.ObjectifiedElement` meta element
-    :ivar body: :class:`lxml.objectify.ObjectifiedElement` body element
-
-    .. seealso::
-        http://www.akomantoso.org/docs/akoma-ntoso-user-documentation/metadata-describes-the-content
+    An Akoma Ntoso Act document.
     """
     document_type = "act"
 
@@ -42,7 +31,8 @@ def empty_document_attrs(cls):
 
     @property
     def publication_name(self):
-        """ Name of the publication in which this act was published """
+        """ Name of the publication in which this act was published.
+        """
         pub = self.get_element('meta.publication')
         return pub.get('name') if pub is not None else None
 
@@ -55,7 +45,8 @@ def publication_name(self, value):
 
     @property
     def publication_date(self):
-        """ Date of the publication """
+        """ Date of publication as a `datetime.date` object.
+        """
         pub = self.get_element('meta.publication')
         if pub is not None and pub.get('date'):
             return parse_date(pub.get('date')).date()
@@ -68,7 +59,8 @@ def publication_date(self, value):
 
     @property
     def publication_number(self):
-        """ Sequence number of the publication """
+        """ Sequence number of the publication.
+        """
         pub = self.get_element('meta.publication')
         return pub.get('number') if pub is not None else None
 
@@ -219,4 +211,7 @@ def __init__(self, date=None, repealing_title=None, repealing_uri=None):
 
 
 class Bill(HierarchicalStructure):
+    """
+    An Akoma Ntoso Bill document.
+    """
     document_type = "bill"

cobalt/schemas.py

@@ -1,3 +1,10 @@
+"""
+Cobalt can validate Akoma Ntoso documents against the Akoma Ntoso schema. Two schemas are provided:
+
+1. Strict: the `official AKN schema <http://docs.oasis-open.org/legaldocml/akn-core/v1.0/os/part2-specs/schemas/akomantoso30.xsd>`_
+2. Lenient: a slightly modified version of the official schema. Duplicate eId attributes are allowed, and FRBRdate
+   elements are allowed to have year-only @date values.
+"""
 import os
 
 from lxml import etree
@@ -47,7 +54,7 @@ def get_schema(namespace, strict):
 
 def assert_validates(akn_doc, strict=False):
     """ Assert that this AKN document validates against the AKN schema.
-    Raises `lxml.etree.DocumentInvalid' if validation fails.
+    Raises `lxml.etree.DocumentInvalid` if validation fails.
     """
     schema = get_schema(akn_doc.namespace, strict)
     schema.assertValid(akn_doc.root)

cobalt/uri.py

@@ -27,8 +27,8 @@
 
 class FrbrUri(object):
     """
-    An FRBR URI parser which understands Akoma Ntoso 3.0 FRBR URIs (IRIs) for works
-    and expressions.
+    An object for working with
+    `Akoma Ntoso 3.0 FRBR URIs <https://docs.oasis-open.org/legaldocml/akn-nc/v1.0/os/akn-nc-v1.0-os.html>`_ (IRIs).
 
     URIs can be parsed from a plain string using :meth:`parse` or they can be
     constructed directly. URIs can be manipulated in-place once constructed,
@@ -87,11 +87,6 @@ class FrbrUri(object):
     :ivar expression_component: name of the expression component, may be None
     :ivar expression_subcomponent: name of the expression subcomponent, may be None
     :ivar format: format extension, may be None
-
-    .. seealso::
-
-       http://akresolver.cs.unibo.it/admin/documentation.html
-       http://www.akomantoso.org/release-notes/akoma-ntoso-3.0-schema/naming-conventions-1/bungenihelpcenterreferencemanualpage.2008-01-09.1484954524
     """
 
     default_language = 'eng'
@@ -116,6 +111,8 @@ def __init__(self, country, locality, doctype, subtype, actor, date, number,
         self.format = format
 
     def clone(self):
+        """ Return a copy of this FrbrUri object.
+        """
         return FrbrUri(
             prefix=self.prefix,
             country=self.country,
@@ -192,6 +189,10 @@ def __str__(self):
 
     @classmethod
     def parse(cls, s):
+        """ Parse a string into an FrbrUri instance.
+
+        :raises ValueError: if parsing fails
+        """
         s = s.rstrip('/')
         match = FRBR_URI_RE.match(s)
         if match:
@@ -206,6 +207,8 @@ def year(self):
 
     @property
     def place(self):
+        """ Full place code, including both country and locality (if present).
+        """
         if self.locality:
             return self.country + "-" + self.locality
         return self.country

docs/api.rst

@@ -1,46 +1,75 @@
-``cobalt``
-=============
+Cobalt API
+==========
 
-.. automodule:: cobalt
+Cobalt has classes for each Akoma Ntoso document type.
 
-    Acts
-    ----
+Base classes
+............
 
-    .. automodule:: cobalt
+.. automodule:: cobalt.akn
+    :members:
 
-        .. autoclass:: Act
-            :members:
+Amendment
+.........
 
-            .. automethod:: __init__
+.. automodule:: cobalt.amendment
+    :members:
+    :show-inheritance:
 
-    .. automodule:: cobalt.toc
+Collection
+..........
 
-        .. autoclass:: TOCBuilder
-            :members:
+.. automodule:: cobalt.collection
+    :members:
+    :show-inheritance:
 
-            .. automethod:: __init__
+Debate
+......
 
-        .. autoclass:: TOCElement
-            :members:
+.. automodule:: cobalt.debate
+    :members:
+    :show-inheritance:
 
-            .. automethod:: __init__
+Hierarchical structure
+......................
 
-    FRBR URIs
-    ---------
+.. automodule:: cobalt.hierarchical
+    :members:
+    :show-inheritance:
 
-    .. automodule:: cobalt.uri
+Judgment
+........
 
-        .. autoclass:: FrbrUri
-            :members:
+.. automodule:: cobalt.judgment
+    :members:
+    :show-inheritance:
 
-            .. automethod:: __init__
+Open structure
+..............
 
-    Rendering
-    ---------
+.. automodule:: cobalt.openstructure
+    :members:
+    :show-inheritance:
 
-    .. automodule:: cobalt.render
+Portion
+..............
 
-        .. autoclass:: HTMLRenderer
-            :members:
+.. automodule:: cobalt.portion
+    :members:
+    :show-inheritance:
 
-            .. automethod:: __init__
+FRBR URIs
+---------
+
+.. automodule:: cobalt.uri
+
+    .. autoclass:: FrbrUri
+        :members:
+
+Schemas and validation
+----------------------
+
+.. automodule:: cobalt.schemas
+
+    .. autofunction:: validate
+    .. autofunction:: assert_validates