Sphinx autoyaml.

docs/conf.py

@@ -45,12 +45,15 @@ import lakesuperior.env_setup
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc',
+extensions = [
+    'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.imgmath',
-    'sphinx.ext.viewcode']
+    'sphinx.ext.viewcode',
+    'sphinxcontrib.autoyaml',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -186,3 +189,6 @@ texinfo_documents = [
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
 
+# Autoyaml extension
+autoyaml_root = path.join(lakesuperior.basedir, 'etc.defaults')
+

docs/index.rst

@@ -30,6 +30,7 @@ Indices and tables
    :maxdepth: 3
    :caption: User Reference
 
+    Configuration <config>
     Discovery & Query <discovery>
     Divergences from Fedora 4 <fcrepo4_deltas>
     Messaging <messaging>

lakesuperior/etc.defaults/application.yml

@@ -1,124 +1,140 @@
-# Default repository configuration.
+### Default repository configuration.
 #
-# Copy this file or parts of it in a separate location to override these
-# settings. Individual items can be selectively overridden as long as the YAML
-# hierarchical structure is kept.
+#   Copy this file or parts of it in a separate location to override these
+#   settings. Individual items can be selectively overridden as long as the YAML
+#   hierarchical structure is kept.
 
-# Set app_mode to either 'prod', 'test' or 'dev'.
-# 'prod' is normal running mode. 'test' is used for running test suites.
-# 'dev' is similar to normal mode but with reload and debug enabled.
+#   Set app_mode to either 'prod', 'test' or 'dev'.
+#   'prod' is normal running mode. 'test' is used for running test suites.
+#   'dev' is similar to normal mode but with reload and debug enabled.
 app_mode: 'prod'
 
-# Base data directory. This contains both volatile files such as PID files,
-# and persistent ones, such as resource data. LDP-NRs will be stored under
-# <basedir>/ldpnr_store and LDP-RSs under <basedir>/ldprs_store.
+### Base data directory.
+#   This contains both volatile files such as PID files,
+#   and persistent ones, such as resource data. LDP-NRs will be stored under
+#   <basedir>/ldpnr_store and LDP-RSs under <basedir>/ldprs_store.
 #
-# If different data files need to be running on different storage hardware,
-# the individual subdirectories can be mounted on different file systems.
+#   If different data files need to be running on different storage hardware,
+#   the individual subdirectories can be mounted on different file systems.
 #
-# If unset, it will default to <lakesuperior package root>/data.
+#   If unset, it will default to <lakesuperior package root>/data.
 data_dir:
 
 # Configuration for binary path and fixity check generation. The hash is a
 # checksumn of the contents of the file.
 uuid:
-    # Algorithm used to calculate the hash that generates the content path.
-    # This can be any one of the Python hashlib functions:
-    # https://docs.python.org/3/library/hashlib.html
+
+    ### Algorithm used to calculate the hash that generates the content path.
+    #   This can be any one of the Python hashlib functions:
+    #   https://docs.python.org/3/library/hashlib.html
     #
-    # This needs to be ``sha1`` if a compatibility with the Fedora4 file layout
-    # is needed, however in security-sensitive environments it is strongly
-    # advised to use a stronger algorithm, since SHA1 is known to be
-    # vulnerable to counterfeiting: see https://shattered.io/
+    #   This needs to be ``sha1`` if a compatibility with the Fedora4 file layout
+    #   is needed, however in security-sensitive environments it is strongly
+    #   advised to use a stronger algorithm, since SHA1 is known to be
+    #   vulnerable to counterfeiting: see https://shattered.io/
     #
-    # `blake2b` is a strong, fast cryptographic alternative to SHA2/3:
-    # https://blake2.net/
+    #   `blake2b` is a strong, fast cryptographic alternative to SHA2/3:
+    #   https://blake2.net/
     algo: sha1
 
 # Data store configuration.
 store:
-    # The semantic store used for persisting LDP-RS (RDF Source) resources.
-    # MUST support SPARQL 1.1 query and update.
+    #   The semantic store used for persisting LDP-RS (RDF Source) resources.
+    #   MUST support SPARQL 1.1 query and update.
     ldp_rs:
-        # store layout. At the moment, only `rsrc_centric_layout`is supported.
+
+        ### Store layout.
+        #   At the moment, only `rsrc_centric_layout`is supported.
         layout: rsrc_centric_layout
 
-        # whether to check if the object of a client-provided triple is the uri
-        # of a repository-managed resource and veify if that exists.
-        # if set to false, properties are allowed to point to resources in the
-        # repositoy that do not exist. also, if a resource is deleted, inbound
-        # relationships may not be cleaned up.
-        # this can be one of `False` (boolean), `lenient` or `strict`. `False`
-        # does not check for referential integrity. `lenient` quietly drops a
-        # user-provided triple if its object violates referential integrity.
-        # `strict` raises an exception.
+        ### whether to check if the object of a client-provided triple is the
+        #   uri of a repository-managed resource and veify if that exists.  if set
+        #   to false, properties are allowed to point to resources in the
+        #   repositoy that do not exist. also, if a resource is deleted, inbound
+        #   relationships may not be cleaned up.  this can be one of `False`
+        #   (boolean), `lenient` or `strict`. `False` does not check for
+        #   referential integrity. `lenient` quietly drops a user-provided triple
+        #   if its object violates referential integrity.  `strict` raises an
+        #   exception.
         #
-        # Changes to this parameter require a full migration.
+        #   Changes to this parameter require a full migration.
         referential_integrity: lenient
 
-        # this mimics Fedora4 behavior which segments an identifier on POST.
+        ### this mimics Fedora4 behavior which segments an identifier on POST.
         legacy_ptree_split: False
 
-    # The path used to persist LDP-NR (bitstreams).
-    # This is for now a POSIX filesystem. Other solutions such as HDFS may be
-    # possible in the future.
+    ### The path used to persist LDP-NR (bitstreams).
+    #   This is for now a POSIX filesystem. Other solutions such as HDFS may be
+    #   possible in the future.
     ldp_nr:
+
         # See store.ldp_rs.layout.
         layout: default_layout
 
-        # How to split the balanced pairtree to generate a path. The hash
-        # string is defined by the uuid.algo parameter value.
-        # This parameter defines how many characters are in each branch. 2-4 is
-        # the recommended setting. NOTE: a value of 2 will generate up to 256
-        # sub-folders in a folder; 3 will generate max. 4096 and 4 will
-        # generate max. 65536. Check your filesystem capabilities before
-        # setting this to a non-default value.
+        ### How to split the balanced pairtree to generate a path.
+        #   The hash string is defined by the uuid.algo parameter value.
+        #   This parameter defines how many characters are in each branch. 2-4 is
+        #   the recommended setting. NOTE: a value of 2 will generate up to 256
+        #   sub-folders in a folder; 3 will generate max. 4096 and 4 will
+        #   generate max. 65536. Check your filesystem capabilities before
+        #   setting this to a non-default value.
         #
-        # Changes to this parameter require a full migration.
+        #   Changes to this parameter require a full migration.
         pairtree_branch_length: 2
 
-        # Max. number of branches to generate. 0 will split the string until
-        # it reaches the end.
-        # E.g. if the hash value is 0123456789abcdef01234565789abcdef and the
-        # branch length value is 2, and the branch number is 4, the path will
-        # be 01/23/45/67/89abcdef01234565789abcdef. For a value of 0 it will be
-        # 01/23/45/67/89/ab/cd/ef/01/23/45/67/89/ab/cd/ef. Be aware that deeply
-        # nested directory structures may tax some of the operating system's
-        # services that scan for files, such as `updatedb`. Check your system
-        # capabilities for maximum nested directories before changing the
-        # default.
+        ### Max. number of branches to generate. 0 will split the string until
+        #   it reaches the end.
+        #   E.g. if the hash value is 0123456789abcdef01234565789abcdef and the
+        #   branch length value is 2, and the branch number is 4, the path will
+        #   be 01/23/45/67/89abcdef01234565789abcdef. For a value of 0 it will be
+        #   01/23/45/67/89/ab/cd/ef/01/23/45/67/89/ab/cd/ef. Be aware that deeply
+        #   nested directory structures may tax some of the operating system's
+        #   services that scan for files, such as `updatedb`. Check your system
+        #   capabilities for maximum nested directories before changing the
+        #   default.
         #
-        # Changes to this parameter require a full migration.
+        #   Changes to this parameter require a full migration.
         pairtree_branches: 4
 
-# Configuration for messaging.
+### Configuration for messaging.
 messaging:
-    # List of channels to send messages to.
-    # Each channel must define the `endpoint` and the `level` parameters.
+
+    ### List of channels to send messages to.
+    #   Each channel must define the `endpoint` and the `level` parameters.
     routes:
-          # Output handler. Currently only `StompHandler` is supported.
+
+        ### Output handler. Currently only `StompHandler` is supported.
         - handler: StompHandler
 
-          # Whether this route is used. It False, no messages will be emitted
-          # for this route.
+          ### Whether this route is used. It False, no messages will be emitted
+          #   for this route.
           active: True
 
-          # Protocol version. One of `10`, `11` or `12`.
+          ### Protocol version. One of `10`, `11` or `12`.
           protocol: '11'
+
+          ### Host IP address.
           host: 127.0.0.1
+
+          ### Host port.
           port: 61613
 
-          # Credentials are optional.
+          ### User name for authentication.
+          #   Credentials are optional.
           username:
+
+          ### Password for authentication.
           password:
+
+          ### Message topic.
           destination: '/topic/fcrepo'
 
-          # Message format: at the moment the following are supported:
-          # - `ASResourceFormatter`: Sends information about a resource being
-          #   created, updated or deleted, by who and when, with no further
-          #   information about what changed.
-          # - `ASDeltaFormatter`: Sends the same information as
-          #   `ASResourceFormatter` with the addition of the triples that were
-          #   added and the ones that were removed in the request. This may be
-          #   used to send rich provenance data to a preservation system.
+          ### Message format: at the moment the following are supported:
+          #   - `ASResourceFormatter`: Sends information about a resource being
+          #     created, updated or deleted, by who and when, with no further
+          #     information about what changed.
+          #   - `ASDeltaFormatter`: Sends the same information as
+          #     `ASResourceFormatter` with the addition of the triples that were
+          #     added and the ones that were removed in the request. This may be
+          #     used to send rich provenance data to a preservation system.
           formatter: ASResourceFormatter

requirements_rtd.txt

@@ -13,5 +13,6 @@ rdflib==4.2.2
 requests-toolbelt>=0.8.0
 requests>=2.18.4
 sphinx-rtd-theme>=0.2.4
+sphinxcontrib-yaml>=1.0.0
 stomp.py>=4.1.20
 wheel>=0.30.0a0