Merge pull request #174 from ngageoint/manpages

.gitlab-ci.yml

@@ -20,7 +20,8 @@ before_script:
   - mkdir -p $GOPATH/src/github.com/ngageoint
   - ln -s $(pwd) $GOPATH/src/github.com/ngageoint/seed-cli
   - cd $GOPATH/src/github.com/ngageoint/seed-cli
-
+  - docker pull rochdev/alpine-asciidoctor:mini
+
 build:
   stage: build
   artifacts:
@@ -30,6 +31,7 @@ build:
     - output/seed-windows-amd64
   script:
     - ./build-cli.sh $CI_COMMIT_TAG
+    - docker run -v readme.adoc:/documents/readme.adoc -v seed-cli.adoc:/documents/seed-cli.adoc --name=seed-man rochdev/alpine-asciidoctor:mini asciidoctor -b manpage -D /documents/output seed-cli.adoc
   only:
     - tags
 

.travis.yml

@@ -10,13 +10,15 @@ install:
   - go get github.com/ngageoint/seed-common/...
   - go get golang.org/x/sys/unix/...
   - go get github.com/zyxar/image2ascii/ascii
+  - docker pull rochdev/alpine-asciidoctor:mini
 
 script:
   - echo "Validating formatting with gofmt..."
   - gofmt -l . | grep -v assets\.go | if [[ $(wc -l | sed 's/ //g')>0 ]] ; then echo gofmt should be run on $(gofmt -l . | grep -v assets\.go); exit 1 ;fi
   - ./build-cli.sh ${TRAVIS_TAG}
   - docker run -d -p 5000:5000 --restart=always --name registry -v `pwd`/auth:/auth -e "REGISTRY_AUTH=htpasswd" -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd registry:2
   - go test ./...
+  - docker run -v $TRAVIS_BUILD_DIR/readme.adoc:/documents/readme.adoc -v $TRAVIS_BUILD_DIR/seed-cli.adoc:/documents/seed-cli.adoc --name=seed-man rochdev/alpine-asciidoctor:mini asciidoctor -b manpage -D /documents/output seed-cli.adoc
 
 deploy:
   # Deployment that pushes GitHub releases of software on tag

readme.adoc

@@ -3,15 +3,19 @@
 image:https://badges.gitter.im/ngageoint/seed.svg[link="https://gitter.im/ngageoint/seed?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]
 image:https://travis-ci.org/ngageoint/seed-cli.svg?branch=master[link="https://travis-ci.org/ngageoint/seed-cli"]
 
+//# tag::intro[]
 The Seed team provides a fully featured Command-Line Interface (CLI) for algorithm developers looking to offer Seed
 compliant packaging of their jobs. Using the CLI will enable you to quickly iterate without getting bogged down
 learning how to interface directly with the underlying container technologies (Docker). It also simplifies the process
 of attaching Seed metadata to your algorithm prior to publish.
+//# end::intro[]
 
 == Usage
 
+//# tag::command-intro[]
 Seed CLI offers sub-commands that correlate to common operations performed by an algorithm developer. These
 can be seen from the command-line by launching the CLI without any arguments:
+//# end::command-intro[]
 
 ----
 seed
@@ -22,12 +26,15 @@ usage can be found in the following sections.
 
 === Build
 
+//# tag::build-usage[]
 The first step when starting to package an algorithm for Seed compliance is to define the requirements and interface.
 This is done by a combination of execution environment configuration (`Dockerfile`), resource requirement definition and
 input / output specification (`seed.manifest.json`). By default, the `seed build` command assumes both a `Dockerfile`
 `seed.manifest.json` reside in the current working directory. Using these two files in conjunction the build command
 is able to construct an re-usable Seed compliant image.
+//# end::build-usage[]
 
+//# tag::build-example[]
 A simple example of this would be the addition-job image.
 
 ----
@@ -38,25 +45,39 @@ This will result in a new Docker image that contains `com.ngageoint.seed.manifes
 constraint: addition-job-0.0.1-seed:1.0.0
 
 This image can now be executed via the `seed run` command or pushed to a remote image registry by way of `seed publish`.
+//# end::build-example[]
+
+//# tag::build-publish-usage[]
+The seed build command also provides the option to automatically publish the image after building via the `-publish` flag. 
+All flags specified by the `seed publish` command are available for use.
+//# end::build-publish-usage[]
 
 === Init
 
-The init command will initalize a directory with a template seed.manifest.json file.  The following command will put
-a template seed.manifest.json file in the examples/job directory:
+//# tag::init-usage[]
+The init command will initalize a directory with a template seed.manifest.json file.  
+//# end::init-usage[]
+
+//# tag::init-example[]
+The following command will put a template seed.manifest.json file in the examples/job directory:
 
 ----
 seed init -d examples/job
 ----
+//# end::init-example[]
 
 === Run
 
+//# tag::run-usage[]
 The primary purpose of the CLI is to easily enable algorithm execution. The common stumbling blocks for new developers
 are being able to feed data into and retrieve out fo the containers as a part of execution. The `seed run` command
 facilitates this through introspection of the Seed interface indicating exactly what input data is required, allowing
 for simply specifying the system locations of data and handling all mounting and output validation and capture
 operations for the developer.
+//# end::run-usage[]
 
-For an Seed interface with a single `inputData.files` element with a `name` of `MY_INPUT` the `seed run` command would
+//# tag::run-example[]
+For a Seed interface with a single `inputData.files` element with a `name` of `MY_INPUT` the `seed run` command would
 be as follows:
 
 ----
@@ -66,12 +87,16 @@ seed run -in process-file:0.1.0-seed:0.1.0 -i MY_INPUT=/tmp/file_input.txt -o /t
 This will volume mount `/tmp/file_input.txt` as read only and `/tmp/outputs` into the container, replacing these values
 with the container relative locations and injecting into the defined `args` placeholders for consumption by the
 algorithm.
+//# end::run-example[]
 
 === Batch
 
+//# tag::batch-usage[]
 Related to the run command, the `seed batch` command will run an image multiple times with varying inputs.  It will take
 an image name and either a directory with files to use as input or a csv file specifying keys and files (preferred).
+//# end::batch-usage[]
 
+//# tag::batch-example[]
 For an Seed interface with two `inputData.files` elements with a `name` of `MY_INPUT` and `MY_INPUT2` the `seed batch` command would
 be as follows:
 
@@ -90,6 +115,7 @@ currentDirectoryInput.txt, input2.txt
 
 The image will be run three times and success or failure will be reported for each run along with the location of any
 output.
+//# end::batch-example[]
 
 === List
 
@@ -101,35 +127,51 @@ seed list
 
 === Search
 
-Allows for discovery of Seed compliant images hosted within a Docker registry. The 'seed search' command will search
-a given registry for repositories (images and all their versions) that end in "-seed".  Here is an example of searching quay.io:
+//# tag::search-usage[]
+Allows for discovery of Seed compliant images hosted within a Docker registry (default is docker.io). 
+//# end::search-usage[]
+
+//# tag::search-example-1[]
+The 'seed search' command will search a given registry for repositories (images and all their versions) that end in 
+"-seed".  Here is an example of searching quay.io:
 
 ----
 seed search -r https://quay.io
 ----
+//# end::search-example-1[]
 
+//# tag::search-example-2[]
 If no registry url is supplied, the search command uses docker hub, which requires a organization (or user) to be specified:
 
 ----
 seed search -o geoint
 ----
+//# end::search-example-2[]
 
+//# tag::search-example-3[]
 If a registry is private, a username and password can be specified with -u and -p options:
 
 ----
 seed search -r http://localhost:5000 -u testuser -p testpassword
 ----
+//# end::search-example-3[]
 
 === Publish
 
+//# tag::publish-usage[]
 Provides a convenient way for algorithm developers to push a Seed image to a registry.  This command will tag a seed
 image appropriately and push it to the specified registry.  If successful, it will then remove the local image as well.
+//# end::publish-usage[]
+
+//# tag::publish-example-1[]
 Here is an example of publishing the extractor image to the geoint organization on docker hub:
 
 ----
 seed publish -in extractor-0.1.0-seed:0.1.0 -r docker.io -o geoint
 ----
+//# end::publish-example-1[]
 
+//# tag::publish-example-2[]
 Publishing will check if an image with the same name and tag exists in the registry and will fail if one is found unless
 either the force flag (-f) is set or a deconflict tag is specified to increase a version number.  A common use case for
 seed algorithm developers is to publish new versions of their image and this can be done by specifying one of the job or
@@ -138,38 +180,60 @@ package version flags.  Here is an example of updating the extractor image to 1.
 ----
 seed publish -in extractor-0.1.0-seed:0.1.0 -r docker.io -o geoint -A -P
 ----
+//# end::publish-example-2[]
 
+//# tag::publish-example-3[]
 This will rebuild the extractor image with the appropriate name & label and publish the image extractor-1.0.0-seed:1.0.0
 to docker hub.  Finally, if the registry is private, a username and password can be specified with -u and -p options:
 
 ----
 seed publish -in extractor-0.1.0-seed:0.1.0 -r localhost:5000 -u testuser -p testpassword
 ----
+//# end::publish-example-3[]
+
+=== Pull
+
+The Pull command will pull the a Seed compliant image from the remote Docker registry. 
+
+//# tag::pull-example[]
+This will pull the extractor-0.1.0-seed:1.0.0 image from the docker.io/geoint registry:
+----
+seed pull -in extractor-0.1.0-seed:0.1.0 -r docker.io -o geoint
+----
+//# end::pull-example[]
 
 === Validate
 
+//# tag::validate-usage[]
 The Validate command will validate a Seed json file against the Seed schema.  This is also done as part of the build and
 run commands, but if a user is having problems getting their Seed file to validate this can be useful to debug without
-those additional steps.  This command will validate the Seed file in the examples/extractor directory:
+those additional steps.
+//# end::validate-usage[]  
+
+//# tag::validate-example-1[]
+This command will validate the Seed file in the examples/extractor directory using the schema built-in to the Seed CLI tool:
 
 ----
 seed validate -d examples/extractor
 ----
+//# end::validate-example-1[]
 
-That will use the schema built-in to the Seed CLI tool.  To use a different schema, pass it in using the -s flag:
+//# tag::validate-example-2[]
+To use a different schema, pass it in using the -s flag:
 
 ----
 seed validate -d examples/extractor -s schema/0.1.0/seed.manifest.schema.json
 ----
+//# end::validate-example-2[]
 
 === Version
-
+//# tag::version[]
 The version command will print the version of the Seed CLI tool:
 
 ----
 seed version
 ----
-
+//# end::version[]
 
 == Development