Merge branch 'master' into 356-end-to-end-tests

Author: Bjwebb

docs/flatten.rst

@@ -58,10 +58,6 @@ CSV files for you, populated with the data from the input JSON file.
 .. csv-table:: sheet: tab_dish.csv
    :file: ../examples/flatten/simple/expected/tab_dish.csv
 
-.. csv-table:: sheet: dish.csv
-   :file: ../examples/flatten/simple/expected/dish.csv
-   :header-rows: 1
-
 .. caution ::
 
    If you forget the `--root-list-path` option and your data isn't under a top

docs/index.rst

@@ -41,6 +41,7 @@ Contents:
    developerguide
    usage-ocds
    usage-360
+   usage-iati
 
 Get started by reading the Spreadsheet Designer's Guide to understand the core
 concepts, how to use the `flatten-tool` command and how to structure your own

docs/unflatten.rst

@@ -1179,6 +1179,61 @@ table" section earlier.
    titles, you can use the schema in the "Arbitrary-depth in a single
    table" section too.
 
+Metadata Tab
+============
+
+Flattentool supports naming of a special sheetname (or Tab) in a spreadsheet to add data to the top level of the returned data structure.  Currently it only supports output format JSON and the input format has to be XLSX.
+
+Example Usage
+-------------
+
+You have a spreadsheet named "mydata.xlsx with" 2 sheets. The first sheet named "Cafe":
+
+.. csv-table::
+   :header-rows: 1
+   :file: ../examples/cafe/meta-tab/data.csv
+
+A second sheet you would like to add some metadata to this list of rows to a sheet named "Meta":
+
+.. csv-table::
+   :file: ../examples/cafe/meta-tab/metadata.csv
+
+As you can see it is also possible to choose to have the metadata headings on the first column (not the first row) with metadata vertical.
+
+The command for doing this:
+
+.. literalinclude:: ../examples/cafe/meta-tab/cmd.txt
+   :language: bash
+
+.. literalinclude:: ../examples/cafe/meta-tab/expected.json
+   :language: json
+
+Options
+-------
+
+`--metatab-name`
+
+This is the name of the sheet with the metadata on. It is case sensitive. It is the only mandatory option if you want to parse a metatab, without it no metatab will be parsed
+
+`--metatab-schema`
+
+The JSON schema of the metatab. This schema will be used to determine the types and/or titles of the data in the metatab.  It works in the same way as the --schema option but just for the metatab.  The schema used with the --schema option has no effect on the metatab parsing, so this has to be specified if you need title handling or want to specify types.
+
+`--metatab-only`
+
+Just return the metatab information and not the rest of the doc. Using the example above:
+
+.. literalinclude:: ../examples/cafe/meta-tab-only/cmd.txt
+   :language: bash
+
+.. literalinclude:: ../examples/cafe/meta-tab-only/expected.json
+   :language: json
+
+`--metatab-vertical-orientation`
+
+Say that the metatab data runs vertically rather that horizontally see example above.
+
+
 Source maps
 ===========
 

docs/usage-iati.rst

@@ -0,0 +1,44 @@
+Flatten-Tool for IATI
+=====================
+
+Currently flatten-tool only supports Spreadsheet->XML for IATI (unflatten), not conversion in the other direction, or automated template creation.
+
+Convert a spreadsheet to XML
+----------------------------
+
+For an xlsx file called ``filename.xlsx``:
+
+.. code-block:: bash
+
+    flatten-tool unflatten --xml --id-name iati-identifier --root-list-path iati-activity -o iati.xml -f xlsx filename.xlsx 
+
+
+For a directory of csv files called ``csv_directory``:
+
+.. code-block:: bash
+
+    flatten-tool unflatten --xml --id-name iati-identifier --root-list-path iati-activity -o iati.xml -f csv csv_directory
+
+(Outputs a file called ``iati.xml``).
+
+
+Example
+-------
+
+Given these two sheets:
+
+.. csv-table:: sheet: main.csv
+   :file: ../examples/iati/main.csv
+
+.. csv-table:: sheet: transactions.csv
+   :file: ../examples/iati/transactions.csv
+
+Running this command:
+
+.. literalinclude:: ../examples/iati/cmd.txt
+   :language: bash
+
+Produces this XML:
+
+.. literalinclude:: ../examples/iati/expected.xml
+   :language: xml

examples/cafe/meta-tab-only/cmd.txt

@@ -0,0 +1 @@
+$ flatten-tool unflatten --input-format=xlsx --metatab-only --metatab-name Meta --metatab-vertical-orientation examples/cafe/meta-tab-only/meta-tab.xlsx

examples/cafe/meta-tab-only/data.csv

@@ -0,0 +1,3 @@
+name,address
+Healthy Cafe,"123 City Street, London"
+Vegetarian Cafe,"42 Town Road, Bristol"

examples/cafe/meta-tab-only/expected.json

@@ -0,0 +1,5 @@
+{
+    "dataLicense": "CC",
+    "rowCount": "2",
+    "publishedDate": "2001-01-01"
+}

examples/cafe/meta-tab-only/meta-tab.xlsx

@@ -0,0 +1,3 @@
+dataLicense,CC
+rowCount,2
+publishedDate,2001-01-01

examples/cafe/meta-tab-only/metadata.csv

@@ -0,0 +1 @@
+$ flatten-tool unflatten --input-format=xlsx --metatab-name Meta --metatab-vertical-orientation examples/cafe/meta-tab/meta-tab.xlsx