From dc44c0d66026d38e4ef808e0f955c27446a7b748 Mon Sep 17 00:00:00 2001
From: meerkat <meerkat@merebox.com>
Date: Mon, 1 Nov 2021 14:29:52 +1100
Subject: [PATCH] Make MD compatible with RtD

---
 docs/source/attributes.md |  8 +++++---
 docs/source/ckan.md       |  3 ++-
 docs/source/comparison.md |  9 ++++++---
 docs/source/conf.py       | 11 ++++++-----
 docs/source/custom.md     |  3 ++-
 docs/source/magda.md      |  3 ++-
 docs/source/martiLQ.md    | 20 ++++++++++++--------
 docs/source/objective.md  |  3 ++-
 docs/source/quality.md    | 12 ++++++++----
 docs/source/references.md |  3 ++-
 docs/source/resources.md  | 12 ++++++++----
 docs/source/what.md       |  3 ++-
 docs/source/when.md       |  6 ++++--
 docs/source/who.md        |  9 ++++++---
 docs/source/why.md        |  9 ++++++---
 15 files changed, 73 insertions(+), 41 deletions(-)

diff --git a/docs/source/attributes.md b/docs/source/attributes.md
index b6e42f5..6b67554 100644
--- a/docs/source/attributes.md
+++ b/docs/source/attributes.md
@@ -1,11 +1,13 @@
-# Attribute definition
+Attribute definition
+====================
 
 A Resource can list attributes related to the document / file.
 
 An attribute is a generic definition and conventions are 
 observed in the definitions that are captured here.
 
-## Attribute definition 
+Attribute definition 
+--------------------
 
 The Attribute consists of:
 
@@ -29,4 +31,4 @@ number of records in the file for the given format.
             "value": "9"
         }
     ]
-```
\ No newline at end of file
+```
diff --git a/docs/source/ckan.md b/docs/source/ckan.md
index e13a69e..cf97138 100644
--- a/docs/source/ckan.md
+++ b/docs/source/ckan.md
@@ -1,4 +1,5 @@
-# CKAN definition
+CKAN definition
+===============
 
 The **martiLQ** has used similar terms and structures that are found in the 
 CKAN API describing the resources.  This similarity allows for simple mapping of values
diff --git a/docs/source/comparison.md b/docs/source/comparison.md
index 23872cf..da9a3bc 100644
--- a/docs/source/comparison.md
+++ b/docs/source/comparison.md
@@ -1,4 +1,5 @@
-# Comparison of martiLQ document definition
+Comparison of martiLQ document definition
+=========================================
 
 The use of metadata definitions is not unique and examples
 exist in many different situations.  Some are standard and open
@@ -22,7 +23,8 @@ a CKAN source into a **martiLQ** document definition and then process the data
 through the pipeline as you would for any other data file that had a
 **martiLQ** document definition.
 
-## Benefit of CKAN and martiLQ
+Benefit of CKAN and martiLQ
+---------------------------
 
 The CKAN is excellent at defining the data source details but it lacks information
 for load quality.  If you have CKAN deployed in your organisation and wish
@@ -31,7 +33,8 @@ CKAN and marti.
 
 Samples exist on CKAN integration.
 
-## Magda and martiLQ
+Magda and martiLQ
+-----------------
 
 Another source of data is [Magda](https://magda.io/) which has API metadata
 definitions.  Magda is more about data federation and as such provides
diff --git a/docs/source/conf.py b/docs/source/conf.py
index a390797..418a854 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -13,7 +13,7 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
-
+from recommonmark.parser import CommonMarkParser
 
 # -- Project information -----------------------------------------------------
 
@@ -43,12 +43,13 @@ exclude_patterns = [
     'samples/powershell/test/*',  
     ]
 
-source_suffix = {
-    '.rst': 'restructuredtext',
-    '.txt': 'restructuredtext',
-    '.md': 'markdown',
+source_parsers = {
+    '.md': CommonMarkParser
 }
 
+source_suffix = ['.rst', '.md']
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
diff --git a/docs/source/custom.md b/docs/source/custom.md
index bf32f49..2ce9685 100644
--- a/docs/source/custom.md
+++ b/docs/source/custom.md
@@ -1,4 +1,5 @@
-# Custom Definition
+Custom Definition
+=================
 
 The custome definition section allows the inclusion of extensions
 to the standard.  To demonstrate the inclusion, there are three
diff --git a/docs/source/magda.md b/docs/source/magda.md
index fd23e3f..27e76fd 100644
--- a/docs/source/magda.md
+++ b/docs/source/magda.md
@@ -1,4 +1,5 @@
-# Magda definitions
+Magda definitions
+=================
 
 https://magda.io/ 
 
diff --git a/docs/source/martiLQ.md b/docs/source/martiLQ.md
index 15d71b4..2bc1166 100644
--- a/docs/source/martiLQ.md
+++ b/docs/source/martiLQ.md
@@ -1,4 +1,5 @@
-# MartiLQ document
+MartiLQ document
+================
 
 The metadata reconciliation transfer information is referred
 to as the **martiLQ** document throughout this documentation.
@@ -6,9 +7,8 @@ to as the **martiLQ** document throughout this documentation.
 The **martiLQ** document can be part of a message or a file
 in its own right. The definition is curently a Json file.
 
-
-
-### Mandatory information
+Mandatory information
+---------------------
 
 The mandatory information is:
 
@@ -16,7 +16,8 @@ The mandatory information is:
 * Unique identifier
 * Resource list - See Resource section summary below or detailed document [Resource](resources.md)
 
-### Optional information
+Optional information
+++++++++++++++++++++
 
 The optional information is:
 
@@ -36,12 +37,14 @@ The optional information is:
 * Custom list - List of custom entries, one being the **martiLQ** software details
   see [custom](custom.md)
 
-### Information extension
+Information extension
++++++++++++++++++++++
 
 The information supplied can be extended by party agreement and there
 are place holders in the defintion.
 
-### Resource 
+Resource 
+--------
 
 The resource section is a list of documents or files that are to be grouped
 together are listed under the same **martiLQ** definition.
@@ -59,7 +62,8 @@ items:
 * Size of document - The document size in bytes
 * URL - This can be ``file://``, ``https://``, ``ftp://``, etc resource location
 
-### Resource optional
+Resource optional
++++++++++++++++++
 
 The following are some of the optional items in the resource section.  See [Resource](resources.md)
 for more details
diff --git a/docs/source/objective.md b/docs/source/objective.md
index 9c08f31..8c9b832 100644
--- a/docs/source/objective.md
+++ b/docs/source/objective.md
@@ -1,4 +1,5 @@
-# MartiLQ objective
+MartiLQ objective
+=================
 
 The objective of **martLQ** is to define a simle standard for
 capturing the data files being transferred.  It is not for 
diff --git a/docs/source/quality.md b/docs/source/quality.md
index ffc1cc4..f843d01 100644
--- a/docs/source/quality.md
+++ b/docs/source/quality.md
@@ -1,11 +1,13 @@
-# Quality definition
+Quality definition
+==================
 
 The **martiLQ** definition allows for the inclusion of load quality 
 definitions.  The load quality definition is intended to be
 able to be applied universally with common tools.  Not 
 all needs are covered with the base definition but can be extended.
 
-## Defined load quality metrics
+Defined load quality metrics
+----------------------------
 
 * Sequential batch number - This is a decimal number defined at the **martiLQ** definition
    and applies to all resources.  The integer portion is for new batches and the fraction
@@ -17,7 +19,8 @@ all needs are covered with the base definition but can be extended.
    on the number of primary segments under root.  JSON records can be counted in a similar way.
    The headers or trailling records are not counted
 
-## Addresses deficiencies 
+Addresses deficiencies 
+----------------------
 
 The **martiLQ** objective is to address deficiencies with alternative 
 data load quality approaches such as:
@@ -29,7 +32,8 @@ data load quality approaches such as:
  * securing the data
  * adding footers to the data, requiring custom file handlers
 
-## Extending load quality metrics 
+Extending load quality metrics 
+------------------------------
 
 **martLQ** framewokr and importantly is open to extension so that extra
 load metrics appropriate to the situation can be included.
diff --git a/docs/source/references.md b/docs/source/references.md
index 7c585fc..207e89d 100644
--- a/docs/source/references.md
+++ b/docs/source/references.md
@@ -1,4 +1,5 @@
-# References
+References
+==========
 
 
 https://dex.dss.gov.au/sites/default/files/documents/2021-06/data-exchange-protocols-june-2021.pdf
diff --git a/docs/source/resources.md b/docs/source/resources.md
index 2219724..09d6497 100644
--- a/docs/source/resources.md
+++ b/docs/source/resources.md
@@ -1,4 +1,5 @@
-# Resources definition
+Resources definition
+====================
 
 The resources section defines the files that are grouped
 together by association.  This association is not defined but can
@@ -38,7 +39,8 @@ The following are optional in the resource section.
 * Encryption - Type of encryption used if any
 
 
-## Compression
+Compression
+-----------
 
 Files can be compressed using a utility.  A single compressed file can contain
 multiple files.  The **martiLQ** definition document applies to the compressed file 
@@ -49,7 +51,8 @@ compressed file.
 
 Compression of files always occur before encryption.
 
-### martiLQ definition for Compressed File
+martiLQ definition for Compressed File
+++++++++++++++++++++++++++++++++++++++
 
 For a compressed file that is not encrypted, the distribution definition will be:
 
@@ -68,7 +71,8 @@ The reason for this approach is it allows a generic tool to be deployed to
 check the validity of the contents without unpacking the received /fetched
 file.  That is you can perform load quality pipeline processing.
 
-## Encryption
+Encryption
+----------
 
 The encryption of content is always applied after compression not before, if
 you are not using the compression tool native encryption.  WinZIP and 7ZIP
diff --git a/docs/source/what.md b/docs/source/what.md
index 1823d2b..db9990f 100644
--- a/docs/source/what.md
+++ b/docs/source/what.md
@@ -1,4 +1,5 @@
-# What is marti
+What is marti
+=============
 
 The foundation pillar for the **martiLQ** framework is the [martiLQ document](martiLQ.md) 
 that defines the reconciliation and other metadata of the document / file being transferred.
diff --git a/docs/source/when.md b/docs/source/when.md
index 9e7f2ae..27ef352 100644
--- a/docs/source/when.md
+++ b/docs/source/when.md
@@ -1,4 +1,5 @@
-# When would you use martiLQ
+When would you use martiLQ
+==========================
 
 You are likely to start using the **martiLQ** framework when:
 
@@ -11,7 +12,8 @@ If you already have a standard and it works for you, and you have no upcoming (l
 initiative that would benefit from the framework, then stick with what you have.  The benefits
 of the framework are unlikely to weigh in your framework.
 
-## Read the material
+Read the material
+-----------------
 
 Please read the material before jumping in and make sure the **martiLQ** framework will
 provide you with the expected benefits.  Implementing the framework and then changing 
diff --git a/docs/source/who.md b/docs/source/who.md
index 3ade812..cb8bf4c 100644
--- a/docs/source/who.md
+++ b/docs/source/who.md
@@ -1,11 +1,13 @@
-# Who is likely to use martiLQ
+Who is likely to use martiLQ
+============================
 
 You are likely to find the **martiLQ** framework relevant if you:
 
 1. Have many document exchanges, such as End of Day batches
 2. Need to verify or reconcile the documents
 
-## Data exchanges
+Data exchanges
+--------------
 
 If you are creating or receiving many documents or files on a regular basis
 then you probably have some framework defined.  The framework may be as simple as:
@@ -22,7 +24,8 @@ Simple framework such as the above have limitations, such as:
 * Lower automation prospects and alignment to DataSecOps
 * Poor fit to web applications (they tend to be designed for FTP and LAN)
 
-## Framework Sidecar files
+Framework Sidecar files
+-----------------------
 
 The **martiLQ** framework addresses the issues and limitations by using sidecar
 or shadow files. The [concept of sidecar files](https://en.wikipedia.org/wiki/Sidecar_file) is 
diff --git a/docs/source/why.md b/docs/source/why.md
index d6a9567..e29eb38 100644
--- a/docs/source/why.md
+++ b/docs/source/why.md
@@ -1,4 +1,5 @@
-# Why use marti
+Why use marti
+=============
 
 **martiLQ** is a framework for providing a degree of auditability and reconciliation of
 documents transferred between systems in an organisation and externally.  It does not intend
@@ -13,7 +14,8 @@ define the format or content of the document.  It defines controls that can be u
 
 You would use **martiLQ** if any of the controls are a requirement for you.
 
-## Documents
+Documents
+---------
 
 Documents in this context are digital storage objects such as operating system files,
 cloud storage objects or blobs.  The document content can have structure and contains multiple
@@ -25,7 +27,8 @@ in single web transactions.  It is for providing controls when moving large amou
 data as one event.  This data are commonly referred to as batch extracts and performed 
 at scheduled times such as end of day.
 
-## Security
+Security
+--------
 
 The framework does not replace your security, inflight encryption or encryption at rest.