Work on documentation

zimeon · Nov 6, 2024 · b8acef1 · b8acef1
1 parent a38039b
commit b8acef1
Show file tree

Hide file tree

Showing 9 changed files with 56 additions and 36 deletions.
diff --git a/docs/api.rst b/docs/api.rst
@@ -1,23 +1,13 @@
-ocfl-py API
-===========
+API Reference
+=============
 
-.. autosummary::
-   :toctree: generated
+The API reference provides detailed descriptions of ocfl-py's classes and
+functions.
 
-   ocfl.object
-   ocfl
-
-.. automodule:: ocfl
-   :members:
-
-.. automodule:: ocfl.object
-   :members:
 
-.. automodule:: ocfl.storage_root
-   :members:
+.. toctree::
+   :maxdepth: 1
 
-.. automodule:: ocfl.inventory
-   :members:
-
-.. automodule:: ocfl.inventory_validator
-   :members:
+   ocfl
+   ocfl.object
+
diff --git a/docs/command_line.rst b/docs/command_line.rst
@@ -18,10 +18,3 @@ Command Line Tools
    :caption: JSON Schema Validation
 
    demo_jsonschema_inventory_validation
-
-There is also a list of error and warning codes generated by `ocfl-validate.py`
-matched against the
-[OCFL Validation Codes](https://ocfl.io/validation/validation-codes.html)
-provided with the specification:
-
-  * [Implementation status for errors and warnings](validation_status.md)
diff --git a/docs/conf.py b/docs/conf.py
@@ -16,24 +16,28 @@
 from pathlib import Path
 sys.path.insert(0, str(Path('..').resolve()))
 
-#import ocfl
-
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = ["myst_parser",
               "sphinx.ext.autodoc",
               "sphinx.ext.autosummary",
+              "sphinx.ext.doctest",
               "sphinx_rtd_theme"]
 myst_enable_extensions = ["colon_fence"]
 
 templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
-
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md']
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'alabaster' #'sphinx_rtd_theme'
+html_theme_options = {
+    'body_max_width' : 'none',
+    'page_width': 'auto',
+}
 html_static_path = ['_static']
+
+# Autodoc
+autodoc_member_order = 'bysource'
diff --git a/docs/conformance.rst b/docs/conformance.rst
@@ -0,0 +1,17 @@
+Conformance
+===========
+
+``ocfl-py`` is designed to follow closely the OCFL specifications.
+
+The following is list of error and warning codes implemented but the ``ocfl-py``
+package. The complete list `OCFL Validation Codes
+<https://ocfl.io/1.1/spec/validation-codes.html>`_ is provided as part of the
+OCFL specifications.
+
+.. toctree::
+   :maxdepth: 1
+
+   validation_status
+
+(The validation status table is generated by the `ocfl-validate.py` script
+run against the ``ocfl`` module.)
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,7 +1,7 @@
-ocfl-py documentation
-=====================
+``ocfl-py`` documentation
+=========================
 
-`ocfl-py` is a Python reference implementation of the Oxford Common File Layout
+``ocfl-py`` is a Python reference implementation of the Oxford Common File Layout
 (OCFL). It provides a number of command-line tools to validate and manipulate
 OCFL Objects and OCFL Storage Roots, a Python library that may be used in other
 code, and additional test fixtures.
@@ -12,4 +12,5 @@ code, and additional test fixtures.
 
    command_line
    api
+   conformance
    fixtures
diff --git a/docs/ocfl.object.rst b/docs/ocfl.object.rst
@@ -0,0 +1,6 @@
+``ocfl.object``
+===============
+
+.. automodule:: ocfl.object
+
+.. autoclass: Object
diff --git a/docs/ocfl.rst b/docs/ocfl.rst
@@ -0,0 +1,5 @@
+``ocfl``
+========
+
+.. automodule:: ocfl
+    :members:
diff --git a/ocfl-object.py b/ocfl-object.py
@@ -27,7 +27,8 @@ def add_common_args(parser, include_version_metadata=False, objdir_required=True
                         help="read from or write to OCFL object directory objdir")
     # Version metadata and object settings
     obj_params = parser.add_argument_group(title="OCFL object parameters")
-    obj_params.add_argument("--spec-version", "--spec", action="store", default="1.1",
+    obj_params.add_argument("--spec-version", "--spec",
+                            action="store", default=ocfl.DEFAULT_SPEC_VERSION,
                             help="OCFL specification version to adhere to")
     obj_params.add_argument("--digest", default="sha512",
                             help="digest algorithm to use")

diff --git a/ocfl/constants.py b/ocfl/constants.py
@@ -5,3 +5,6 @@
 
 SPEC_VERSIONS_SUPPORTED = ("1.0", "1.1")
 """tuple of str: OCFL specification version numbers supported by ocfl-py."""
+
+DEFAULT_SPEC_VERSION = "1.1"
+"""str: OCFL specification version number to assume if none specified."""