Merge branch 'main' into v2

zimeon · Nov 6, 2024 · 808e598 · 808e598
2 parents c25854b + 85eec0f
commit 808e598
Show file tree

Hide file tree

Showing 21 changed files with 253 additions and 212 deletions.
diff --git a/DEV_NOTES.md b/DEV_NOTES.md
@@ -0,0 +1,14 @@
+# Development Notes
+
+## Testing Sphinx documentation build
+
+```
+> sphinx-autobuild docs docs/_build
+```
+
+Then access <http://127.0.0.1:8000/>
+
+Some RTD examples using sphinx:
+* <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html>
+* <https://simpy.readthedocs.io/en/latest/index.html>
+* <https://apt-team.pages.debian.net/python-apt/library/index.html>
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,30 @@
 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_default_options = {
+    "autoclass_content": "both"
+}
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/demo_using_bagit_bags.md b/docs/demo_using_bagit_bags.md
@@ -161,8 +161,8 @@ Taking the newly created OCFL object `/tmp/obj` we can `--extract` the `v4` cont
 INFO:root:Extracted v4 into tmp/extracted_v4
 INFO:bagit:Creating bag for directory tmp/extracted_v4
 INFO:bagit:Creating data directory
-INFO:bagit:Moving my_content to tmp/extracted_v4/tmp0vu88z7y/my_content
-INFO:bagit:Moving tmp/extracted_v4/tmp0vu88z7y to data
+INFO:bagit:Moving my_content to tmp/extracted_v4/tmpp2zau7cu/my_content
+INFO:bagit:Moving tmp/extracted_v4/tmpp2zau7cu to data
 INFO:bagit:Using 1 processes to generate manifests: sha512
 INFO:bagit:Generating manifest lines for file data/my_content/dracula.txt
 INFO:bagit:Generating manifest lines for file data/my_content/dunwich.txt
@@ -184,12 +184,12 @@ We note that the OCFL object had only one `content` file in `v4` but the extract
 diff -r tmp/extracted_v4/bag-info.txt tests/testdata/bags/uaa_v4/bag-info.txt
 1,2c1
 < Bag-Software-Agent: bagit.py v1.8.1 <https://github.com/LibraryOfCongress/bagit-python>
-< Bagging-Date: 2024-11-03
+< Bagging-Date: 2024-11-06
 ---
 > Bagging-Date: 2020-01-04
 diff -r tmp/extracted_v4/tagmanifest-sha512.txt tests/testdata/bags/uaa_v4/tagmanifest-sha512.txt
 2c2
-< 3379553ab3cdfee56b1ebe6dba9118e340fc3b7fcc5ff9aa76ee7123ad7cad89842cb47a0861afe43a1c0cbcd208bd42b4b9790d7b4525cb0b6299cc76fdf817 bag-info.txt
+< 175cfaadd50d9f8c0c9b0e8bd4049be9bf83f286598d5c60e23c6d5be8dd1a937eab03ea188ffcc95e1737c27012f58a7c289c62645168ec5a682f028763b784 bag-info.txt
 ---
 > 10624e6d45462def7af66d1a0d977606c7b073b01809c1d42258cfab5c34a275480943cbe78044416aee1f23822cc3762f92247b8f39b5c6ddc5ae32a8f94ce5 bag-info.txt
 ```

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,7 @@
+``ocfl.object``
+===============
+
+.. automodule:: ocfl.object
+
+.. autoclass:: Object
+   :members:
diff --git a/docs/ocfl.rst b/docs/ocfl.rst
@@ -0,0 +1,5 @@
+``ocfl``
+========
+
+.. automodule:: ocfl
+    :members: