Merge pull request #34 from ascmitc/dev/doc-content-update

Add readme to rst for documentation generation.
ascmitc · Oct 12, 2020 · fbf22d8 · fbf22d8
2 parents e229720 + 2c7ccb0
commit fbf22d8
Show file tree

Hide file tree

Showing 6 changed files with 25 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 
 Ensuring file integrity when backing up and verifying files during production and post production is of utmost importance. The ASC MHL is used to create a chain of custody by tracking each and every copy made between the media’s initial download on set, all the way through to final archival.
 
-The ASC MHL uses common checksum methods for hashing files and folders, but standardizes what information is gathered, where the checksum is placed, and documents these hashes together with essential file metadata in an XML format that is human readable.
+The ASC MHL uses common checksum methods for hashing files and folders, specifies what information is gathered, where the checksum is placed, and documents these hashes together with essential file metadata in an XML format that is human readable.
 
 This repository holds all information about the document format,  a reference implementation, and tools.
 
@@ -52,7 +52,7 @@ The ASC MHL tool implementation can
 * output information about recorded history (summary of history or detailed information about single files), and
 * verify files and entire file hierarchies.
 
-Typical scenarios, sample CLI output, and generated ASC MHL files can be found in the [README.md](examples/scenarios/README.md) file in the ``examples/scenarios`` folder.
+Typical scenarios, sample CLI output, and generated ASC MHL files can be found in the [README.md](https://github.com/ascmitc/mhl/blob/master/examples/scenarios/) file in the ``examples/scenarios`` folder of the git repository.
 
 The documentation can also be found at [https://ascmhl.readthedocs.io/](https://ascmhl.readthedocs.io/)
 
@@ -65,18 +65,15 @@ For installing system dependencies on macOS [Homebrew](https://brew.sh) is recom
 
 ### System requirements
 
-```shell
-$ ./ascmhl.py --help
-$ ./ascmhl.py verify --help
-```
-
 Make sure you have Python 3 installed:
 
 ```shell
 $ brew install python3
 $ brew postinstall python3
 ```
 
+### Installing `ascmhl` manually
+
 Download the source code and install dependencies using a [Virtual Environment](https://docs.python.org/3/tutorial/venv.html):
 
 ```shell
@@ -87,10 +84,10 @@ $ source env/bin/activate
 $ pip3 install -r requirements.txt
 ```
 
-> As of now, this process has only been tested on macOS 10.13.
+> As of now, this process has only been tested on macOS 10.13 and 10.14.
 
 
-## Installing `ascmhl`
+### Installing `ascmhl` via package manager
 
 > TBD
 

diff --git a/docs/source/requirements.txt → docs/requirements.txt b/docs/source/requirements.txt → docs/requirements.txt
@@ -1,6 +1,7 @@
 # use our project root requirements
 # add doc gen requirements to base requirements.
--r ../../requirements.txt
+-r ../requirements.txt
 Sphinx==3.1.2
 sphinx-click==2.5.0
 sphinx-rtd-theme==0.5.0
+recommonmark==0.6.0
diff --git a/docs/source/README.md b/docs/source/README.md
@@ -0,0 +1 @@
+../../README.md
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -32,6 +32,7 @@
 extensions = [
     'sphinx_click',
     'sphinx_rtd_theme',
+    'recommonmark',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,11 +6,22 @@
 Welcome to ascmhl's documentation!
 ==================================
 
+This documentation is for the ASC MHL command line tool ``ascmhl`` hosted on https://github.com/ascmitc/mhl.
+
+The ASC MHL tool can
+
+* create and extend ASC MHL history for given files and entire file hierarchies in a file system,
+* output information about recorded history, and
+* verify files and entire file hierarchies.
+
+The "commands" section of this documentation is auto-generated from the Python source code, while the "ASC Media Hash List (ASC MHL)" section with detailled information is imported from the REAMDE.md of the ghithub repoistory at https://github.com/ascmitc/mhl.
+
+
 .. toctree::
    :maxdepth: 3
    :caption: Contents:
 
-   installation
+   README
    commands
 
 
@@ -19,5 +30,7 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
+
+
+This documentation is created automatically from https://github.com/ascmitc/mhl.
diff --git a/docs/source/installation.rst b/docs/source/installation.rst