Fix doc formatting

5 files changed, 86 insertions, 10 deletions

diff --git a/common.mk b/common.mk
index 12a6f70..a40f667 100644
--- a/common.mk
+++ b/common.mk
@@ -33,6 +33,7 @@ release:
 	    $${EDITOR:-emacs} $$TAG_MSG; \
 	    if [[ -f Changes.md ]]; then cat $$TAG_MSG <(echo) Changes.md | sponge Changes.md; git add Changes.md; fi; \
 	    if [[ -f Changes.rst ]]; then cat <(pandoc --from markdown --to rst $$TAG_MSG) <(echo) Changes.rst | sponge Changes.rst; git add Changes.rst; fi; \
+	    PYTHONUNBUFFERED=1 yq --help > docs/cli-doc.txt; git add docs/cli-doc.txt;
 	    git commit -m ${TAG}; \
 	    git tag --sign --annotate --file $$TAG_MSG ${TAG}
 	git push --follow-tags
diff --git a/docs/Makefile b/docs/Makefile
index 41890fe..937174d 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/changelog.rst b/docs/changelog.rst
new file mode 100644
index 0000000..26f8d0e
--- /dev/null
+++ b/docs/changelog.rst
@@ -0,0 +1,3 @@
+Release Notes
+=============
+.. include:: ../Changes.rst
diff --git a/docs/cli-doc.txt b/docs/cli-doc.txt
new file mode 100644
index 0000000..be43d98
--- /dev/null
+++ b/docs/cli-doc.txt
@@ -0,0 +1,76 @@
+usage: yq [options] <jq filter> [YAML file...]
+          [--indentless-lists] [--version]
+          jq_filter [files [files ...]]
+
+yq: Command-line YAML processor - jq wrapper for YAML documents
+
+yq transcodes YAML documents to JSON and passes them to jq.
+See https://github.com/kislyuk/yq for more information.
+
+positional arguments:
+  jq_filter
+  files
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --yaml-output, --yml-output, -y
+                        Transcode jq JSON output back into YAML and emit it
+  --yaml-roundtrip, --yml-roundtrip, -Y
+                        Transcode jq JSON output back into YAML and emit it.
+                        Preserve YAML tags and styles by representing them as extra items
+                        in their enclosing mappings and sequences while in JSON. This option
+                        is incompatible with jq filters that do not expect these extra items.
+  --width WIDTH, -w WIDTH
+                        When using --yaml-output, specify string wrap width
+  --indentless-lists, --indentless
+                        When using --yaml-output, indent block style lists (sequences)
+                        with 0 spaces instead of 2
+  --version             show program's version number and exit
+
+jq - commandline JSON processor [version 1.6]
+
+Usage:	jq [options] <jq filter> [file...]
+	jq [options] --args <jq filter> [strings...]
+	jq [options] --jsonargs <jq filter> [JSON_TEXTS...]
+
+jq is a tool for processing JSON inputs, applying the given filter to
+its JSON text inputs and producing the filter's results as JSON on
+standard output.
+
+The simplest filter is ., which copies jq's input to its output
+unmodified (except for formatting, but note that IEEE754 is used
+for number representation internally, with all that that implies).
+
+For more advanced filters see the jq(1) manpage ("man jq")
+and/or https://stedolan.github.io/jq
+
+Example:
+
+	$ echo '{"foo": 0}' | jq .
+	{
+		"foo": 0
+	}
+
+Some of the options include:
+  -c               compact instead of pretty-printed output;
+  -n               use `null` as the single input value;
+  -e               set the exit status code based on the output;
+  -s               read (slurp) all inputs into an array; apply filter to it;
+  -r               output raw strings, not JSON texts;
+  -R               read raw strings, not JSON texts;
+  -C               colorize JSON;
+  -M               monochrome (don't colorize JSON);
+  -S               sort keys of objects on output;
+  --tab            use tabs for indentation;
+  --arg a v        set variable $a to value <v>;
+  --argjson a v    set variable $a to JSON value <v>;
+  --slurpfile a f  set variable $a to an array of JSON texts read from <f>;
+  --rawfile a f    set variable $a to a string consisting of the contents of <f>;
+  --args           remaining arguments are string arguments, not files;
+  --jsonargs       remaining arguments are JSON arguments, not files;
+  --               terminates argument processing;
+
+Named arguments are also available as $ARGS.named[], while
+positional arguments are available as $ARGS.positional[].
+
+See the manpage for more options.
diff --git a/docs/index.rst b/docs/index.rst
index 33dc03e..781dfb4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,15 +1,9 @@
 .. include:: ../README.rst
 
-API documentation
-=================
-
-.. automodule:: yq
-   :members:
-
-Release Notes
-=============
-.. include:: ../Changes.rst
+CLI usage
+=========
 
+.. literalinclude:: cli-doc.txt
 
 Table of Contents
 =================
@@ -17,6 +11,8 @@ Table of Contents
 .. toctree::
    :maxdepth: 5
 
+   changelog
+
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`