Expand documentation

Author: pont-us

docs/installing.md

@@ -5,8 +5,40 @@ conda-forge channel.
 
 ## Installing from conda-forge
 
-TODO
+Using mamba, conda, or any other conda-compatible package manager, you can
+install xcengine into the current environment with a command like
+
+```bash
+mamba install -c conda-forge xcengine
+```
+
+You can create a new environment containing xcengine with a command like
+
+```bash
+mamba create -c conda-forge xcengine
+```
 
 ## Installing directly from the GitHub repository
 
-TODO
+If you want to work with the latest, unreleased development version of xcengine,
+you can install it from the GitHub repository.
+
+First, clone the repository and change to its root directory:
+
+```bash
+git clone https://github.com/xcube-dev/xcengine.git
+cd xcengine
+```
+
+Next, create a conda environment containing the dependencies and activate it:
+
+```bash
+mamba env create -f environment.yml
+mamba activate xcengine
+```
+
+Finally, install xcengine itself from the repository using pip:
+
+```bash
+pip install --no-deps --editable .
+```

docs/notebook.md

@@ -15,9 +15,9 @@ cell in a notebook, and it is strongly advised that the parameters cell appear
 **as early as possible** in the notebook.
 
 You turn a normal code cell into a parameters cell by adding a tag called
-**parameters** to it in the Jupyter Lab using the Property Inspector.
-(The Property Inspector can be opened by clicking the gear icon at the top
-right of the Jupyter Lab window.)
+**parameters** to it in Jupyter Lab using the Property Inspector. (The Property
+Inspector can be opened by clicking the gear icon at the top right of the Jupyter
+Lab window.)
 
 ![Property inspector](images/property-inspector.png)
 

docs/testing.md

@@ -1,11 +1,20 @@
-# Testing and running application packages
+# Testing and running Application Packages
 
-TODO
+Application Packages are generally deployed to cloud platforms, but there are also
+ways to run CWL files and complete Application Packages locally.
 
 ## Running with cwltool
 
-TODO
+[cwltool](https://www.commonwl.org/user_guide/introduction/quick-start.html) is the
+reference runner for CWL files. It doesn't implement the full Application Package
+best practice (so there is no stage-in / stage-out functionality) but can nevertheless
+be used to run CWL files that implement Application Packages.
 
 ## Running with ZOO-Project and the DRU extensions
 
-TODO
+For a fully functional, locally deployable Application Package platform you can
+use the [ZOO-Project](https://zoo-project.org/) with the optional
+[DRU extensions](https://zoo-project.github.io/docs/kernel/dru.html), running on
+[minikube](https://minikube.sigs.k8s.io/docs/). The
+[EOEPCA+ documentation](https://eoepca.readthedocs.io/projects/deploy/en/2.0-rc1/building-blocks/oapip-engine/)
+gives detailed instructions for installation.

docs/xcetool.md

@@ -6,22 +6,41 @@ The command-line interface to xcengine is the command `xcetool`, which
 implements multiple subcommands and options for building and running
 container images and Application Packages.
 
+You can use the `--help` flag for any `xcetool` command or subcommand to get more
+details on usage and available options.
+
 ### `xcetool image build`
 
-TODO
+This is the main `xcetool` subcommand: it builds a container image from a supplied
+notebook and environment file. If given the `--eoap` argument, it also generates
+a CWL file defining a corresponding application package.
 
 ### `xcetool image run`
 
-TODO
+This subcommand runs an xcengine container image. An image can also be run using the
+`docker run` command, but `xcetool image run` provides some additional convenience
+(e.g. easy configuration of the HTTP port).
 
-###`xcetool make-script` 
+### `xcetool make-script` 
 
-TODO
+This subcommand does not generate a container image, but a directory containing
+the main contents that the image would have had: a script derived from the notebook
+along with some supporting files. The `make-script` subcommand is mainly useful for
+debugging.
 
 ## Publishing your container image
 
-TODO
+Once you have built your container image locally, you can push it to an online
+registry. The tag is used to determine the registry and repository to which to
+push the image. For example, if an image is tagged `quay.io/alice/helloworld:1.0`,
+pushing it will attempt to upload the image to the repository `helloworld`
+under the account `alice` on the registry `quay.io`.
+
+
+## Deploying your Application Package
 
-## Deploying your application package
+Once your container image has been pushed to a registry, the CWL file can be deployed
+to a cloud platform to make your Application Package available to users of this
+platform. The process for deploying the CWL file varies; consult the platform
+documentation or support for details.
 
-TODO