From 1f23a4245d4e7b8c2faf365190d0997249190c0e Mon Sep 17 00:00:00 2001
From: Ian Stride <ianstride@gmail.com>
Date: Thu, 7 Dec 2023 13:36:56 +0000
Subject: [PATCH] Move additional documentation to docs directory (#71)

To keep the README as clear and focused as possible.
---
 README.md               | 56 ++++++++---------------------------------
 docs/rapidpro-import.md | 40 +++++++++++++++++++++++++++++
 docs/transcode.md       | 17 +++++++++++++
 3 files changed, 68 insertions(+), 45 deletions(-)
 create mode 100644 docs/rapidpro-import.md
 create mode 100644 docs/transcode.md

diff --git a/README.md b/README.md
index 958d9fc..3651127 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # ParentText Pipeline
 
-Handles the process for producing RapidPro flows from data held in Google Sheets.
+Handles the process for producing RapidPro flows from data held in spreadsheets.
 
 # Setup
 
@@ -17,51 +17,17 @@ To start the pipeline:
 python -m parenttext_pipeline.cli
 ```
 
-You will need to create a file called 'config.py', in the current working directory, and define a callable called 'create_config' that returns the pipeline settings as a dict. More details can be in the [configuration page].
+You will need to create a file called 'config.py', in the current working directory, and define a callable called 'create_config' that returns the pipeline settings as a dict. More details can be in the [configuration page][config].
 
-# RapidPro flow importer
+# Documentation
 
-A user account on a RapidPro server is required.
+- [Configuration][config] - details of configuration options for the pipeline
+- [RapidPro flow importer] - to automatically import flow definitions into RapidPro
+- [Archive tool] - to create snapshots of source Google Sheets to support repeatable pipeline runs
+- [Transcode tool] - to prepare video and audio files that may be used by ParentText applications
 
-## CLI
 
-```
-rpimport --help
-```
-
-## Python import
-
-```
-from parenttext_pipeline.importer import import_definition
-
-import_definition(
-    host,
-    username,
-    password,
-    definition_file,
-)
-```
-
-# Archive tool
-
-Used to create snapshots of source Google Sheets to support repeatable pipeline runs. See [archive tool docs] for details.
-
-
-# Transcode
-
-ParentText chatbots need supporting media files. This project contains a script that will transcode source video files to video and audio files that meet the ParentText specification.
-
-## Requirements
-
-The script uses the [FFmpeg] command, so it will need to be installed before the script can be used.
-
-## CLI
-
-```
-python -m parenttext.transcode --help
-```
-
-
-[configuration page]: docs/configuration.md
-[archive tool docs]: docs/archive.md
-[FFmpeg]: https://ffmpeg.org/
+[config]: docs/configuration.md
+[Archive tool]: docs/archive.md
+[RapidPro flow importer]: docs/rapidpro-import.md
+[Transcode tool]: docs/transcode.md
diff --git a/docs/rapidpro-import.md b/docs/rapidpro-import.md
new file mode 100644
index 0000000..2265069
--- /dev/null
+++ b/docs/rapidpro-import.md
@@ -0,0 +1,40 @@
+# Requirements
+
+- URL of a RapidPro host
+- Account credentials (username, password) for a user with the 'Editor' role in a RapidPro workspace
+- One or more flow definition (JSON) files to upload
+
+# Run
+
+## CLI
+
+The command itself provides information on usage:
+
+```
+rpimport --help
+```
+
+For example:
+
+```
+rpimport --host https://example.com --user example --password pass flow_definition_1.json flow_definition_2.json
+```
+
+## Python import
+
+From within your own Python script/application:
+
+```
+from parenttext_pipeline.importer import import_definition
+
+import_definition(
+    "https://example.com",
+    "example",
+    "pass",
+    ["definition_file_1.json", "definition_file_2.json"],
+)
+```
+
+# CI/CD
+
+When running within continuous integration/deployment software, it is recommended that the password be kept secret at all times. The importer tool will not print any log messages containing the password.
diff --git a/docs/transcode.md b/docs/transcode.md
new file mode 100644
index 0000000..9cb926f
--- /dev/null
+++ b/docs/transcode.md
@@ -0,0 +1,17 @@
+# Overview
+
+ParentText chatbots need supporting media files. This project contains a script that will transcode source video files to video and audio files that meet the ParentText specification.
+
+## Requirements
+
+- Install the [FFmpeg] command
+- Obtain source video files
+
+## CLI
+
+```
+python -m parenttext.transcode --help
+```
+
+
+[FFmpeg]: https://ffmpeg.org/