More documentation and bash-completion script

- Added more documentation
- Added bash-completion script
- Moved hidden command "tree" to conditional compiling. Now there is a
  separated build for docs-enabled dbdeployer
- Added ability of producing more documentation using command "tree"

Changelog

@@ -1,3 +1,9 @@
+1.1.1	02-Apr-2018
+	- Added more documentation
+	- Added bash-completion script
+	- Moved hidden command "tree" to conditional compiling.
+	  Now there is a separated build for docs-enabled dbdeployer
+	- Added ability of producing more documentation using command "tree"
 1.1.0	30-Mar-2018
 	- Added ability of handling environment variables
 	  in configuration file. $HOME and $PWD are expanded

README.md

@@ -3,6 +3,8 @@
 [DBdeployer](https://github.com/datacharmer/dbdeployer) is a tool that deploys MySQL database servers easily.
 This is a port of [MySQL-Sandbox](https://github.com/datacharmer/mysql-sandbox), originally written in Perl, and re-designed from the ground up in [Go](https://golang.org). See the [features comparison](https://github.com/datacharmer/dbdeployer/blob/master/docs/features.md) for more detail.
 
+Documentation updated for version 1.1.0 (01-Apr-2018 13:08 UTC)
+
 ## Installation
 
 The installation is simple, as the only thing you will need is a binary executable for your operating system.
@@ -11,7 +13,7 @@ Get the one for your O.S. from [dbdeployer releases](https://github.com/datachar
 
 For example:
 
-    $ VERSION=0.3.1
+    $ VERSION=1.1.0
     $ origin=https://github.com/datacharmer/dbdeployer/releases/download/$VERSION
     $ wget $origin/dbdeployer-$VERSION.linux.tar.gz
     $ tar -xzf dbdeployer-$VERSION.linux.tar.gz
@@ -537,6 +539,69 @@ The lock can also be reverted using
 
     $ dbdeployer admin unlock sandbox_name
 
+## Generating additional documentation
+
+Between this file and [the API API list](https://github.com/datacharmer/dbdeployer/blob/master/docs/API-1.1.md), you have all the existing documentation for dbdeployer.
+Should you need additional formats, though, dbdeployer is able to generate them on-the-fly. Tou will need the docs-enabled binaries: in the distribution list, you will find:
+
+* dbdeployer-1.1.0-docs.linux.tar.gz
+* dbdeployer-1.1.0-docs.osx.tar.gz
+* dbdeployer-1.1.0.linux.tar.gz
+* dbdeployer-1.1.0.osx.tar.gz
+
+The executables containing ``-docs`` in their name have the same capabilities of the regular ones, but in addition they can run the *hidden* command ``tree``, with alias ``docs``.
+
+This is the command used to help generating the API documentation. In addition to the API template, the ``tree`` command can produce:
+
+* man pages;
+* Markdown documentation;
+* Restructured Text pages;
+* Command line completion script (see next section).
+
+    $ dbdeployer-docs tree -h
+    This command is only used to create API documentation. 
+    You can, however, use it to show the command structure at a glance.
+
+    Usage:
+      dbdeployer tree [flags]
+
+    Aliases:
+      tree, docs
+
+    Flags:
+          --api               Writes API template
+          --bash-completion   creates bash-completion file
+      -h, --help              help for tree
+          --man-pages         Writes man pages
+          --markdown-pages    Writes Markdown docs
+          --rst-pages         Writes Restructured Text docs
+          --show-hidden       Shows also hidden commands
+
+
+
+## Command line completion
+
+There is a file ``./docs/dbdeployer_completion.sh``, which is automatically generated with dbdeployer API documentation. If you want to use bash completion on the command line, simply copy the file to the bash completion directory. For example:
+
+    # Linux
+    $ sudo cp ./docs/dbdeployer_completion.sh /etc/bash_completion.d
+    $ source /etc/bash_completion
+
+    # OSX
+    $ sudo cp ./docs/dbdeployer_completion.sh /usr/local/etc/bash_completion.d
+    $ source /usr/local/etc/bash_completion
+
+Then, you can use completion as follows:
+
+    $ dbdeployer [tab]
+        admin  defaults  delete  deploy  global  sandboxes  unpack  usage  versions
+    $ dbdeployer dep[tab]
+    $ dbdeployer deploy [tab][tab]
+        multiple     replication  single
+    $ dbdeployer deploy s[tab]
+    $ dbdeployer deploy single --b[tab][tab]
+        --base-port=     --bind-address=
+
 ## Semantic versioning
 
 As of version 1.0.0, dbdeployer adheres to the principles of [semantic versioning](https://semver.org/). A version number is made of Major, Minor, and Revision. When changes are applied, the following happens:
@@ -545,5 +610,7 @@ As of version 1.0.0, dbdeployer adheres to the principles of [semantic versionin
 * Backward-compatible new features increment the **Minor** number.
 * Backward incompatible changes (either features or bug fixes that break compatibility with the API) increment the **Major** number.
 
-The starting API is defined in [API-1.0.md](https://github.com/datacharmer/dbdeployer/blob/master/docs/API-1.0.md).
+The starting API is defined in [API-1.0.md](https://github.com/datacharmer/dbdeployer/blob/master/docs/API-1.0.md) (generated manually.)
+The file [API-1.1.md](https://github.com/datacharmer/dbdeployer/blob/master/docs/API-1.1.md) contains the same API definition, but was generated automatically and can be used to better compare the initial API with further version.
+
 

build.sh

@@ -2,6 +2,13 @@
 target=$1
 version=$2
 
+docs_flags=""
+docs_tag=""
+if [ -n "$DBDEPLOYER_DOCS" -o -n "$MKDOCS" ]
+then
+    docs_flags="--tags docs"
+    docs_tag="-docs"
+fi
 if [ -z "$version" ]
 then
     echo "Syntax: target  version"
@@ -15,20 +22,23 @@ case $target in
         $0 linux $version
         ;;
     OSX)
-        executable=dbdeployer-$version.osx
-	    env GOOS=darwin GOARCH=386 go build -o $executable .
+        executable=dbdeployer-${version}${docs_tag}.osx
+	    (set -x
+        env GOOS=darwin GOARCH=386 go build $docs_flags -o $executable .
+        )
         tar -c $executable | gzip -c > ${executable}.tar.gz
-        ls -lh $executable*
     ;;
     linux)
-        executable=dbdeployer-$version.linux
-	    env GOOS=linux GOARCH=386 go build -o $executable .
+        executable=dbdeployer-${version}${docs_tag}.linux
+        (set -x
+	    env GOOS=linux GOARCH=386 go build $docs_flags -o $executable .
+        )
         tar -c $executable | gzip -c > ${executable}.tar.gz
-        ls -lh $executable*
     ;;
     *)
         echo unrecognized target.
         exit 1
         ;;
 esac
 
+ls -lh dbdeployer-${version}*

cmd/single.go

@@ -155,12 +155,14 @@ func SingleSandbox(cmd *cobra.Command, args []string) {
 	sandbox.CreateSingleSandbox(sd, args[0])
 }
 
+/*
 func ReplacedCmd(cmd *cobra.Command, args []string) {
 	invoked := cmd.Use
 	fmt.Printf("The command \"%s\" has been replaced.\n",invoked)
 	fmt.Printf("Use \"dbdeployer deploy %s\" instead.\n",invoked)
 	os.Exit(0)
 }
+*/
 
 var singleCmd = &cobra.Command{
 	Use: "single MySQL-Version",
@@ -180,6 +182,7 @@ Use the "unpack" command to get the tarball into the right directory.
 	Run: SingleSandbox,
 }
 
+/*
 var (
 	hiddenSingleCmd = &cobra.Command{
 		Use: "single",
@@ -201,11 +204,12 @@ var (
 		Run: ReplacedCmd,
 	}
 )
+*/
 
 func init() {
-	rootCmd.AddCommand(hiddenSingleCmd)
-	rootCmd.AddCommand(hiddenReplicationCmd)
-	rootCmd.AddCommand(hiddenMultipleCmd)
+	//rootCmd.AddCommand(hiddenSingleCmd)
+	//rootCmd.AddCommand(hiddenReplicationCmd)
+	//rootCmd.AddCommand(hiddenMultipleCmd)
 	deployCmd.AddCommand(singleCmd)
 	singleCmd.PersistentFlags().Bool("master", false, "Make the server replication ready")
 

cmd/tree.go

@@ -13,26 +13,118 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// +build docs
+
 package cmd
 
 import (
 	"fmt"
+	"os"
 	"strings"
 	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+	"github.com/datacharmer/dbdeployer/common"
 )
 
-func ShowTree(cmd *cobra.Command, args []string) {
+func WriteApi(show_hidden bool) {
+	fmt.Println("This is the list of commands and modifiers available for")
+	fmt.Println("dbdeployer {{.Version}} as of {{.Date}}")
+	fmt.Println("")
+	fmt.Println("# main")
+	fmt.Println("{{dbdeployer -h }}")
+	fmt.Println("")
+	fmt.Println("{{dbdeployer-docs tree }}")
+	traverse(rootCmd, "", 0, true, show_hidden)
+}
+
+func WriteBashCompletion() {
+	completion_file := "dbdeployer_completion.sh"
+	rootCmd.GenBashCompletionFile(completion_file)
+	fmt.Printf("Copy %s to the completion directory (/etc/bash_completion.d or /usr/local/etc/bash_completion.d)\n",completion_file)
+
+}
+
+func WriteManPages() {
+	man_dir := "man_pages"
+	if common.DirExists(man_dir) {
+		fmt.Printf("manual pages directory '%s' exists already.\n",man_dir)
+		os.Exit(1)
+	}
+	common.Mkdir(man_dir)
+	header := &doc.GenManHeader{
+		Title: "dbdeployer",
+		Section: "1",
+	}
+	err := doc.GenManTree(rootCmd, header, man_dir)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	fmt.Printf("Man pages generated in '%s'\n", man_dir)
+}
+
+func WriteMarkdownPages() {
+	md_dir := "markdown_pages"
+	if common.DirExists(md_dir) {
+		fmt.Printf("Markdown pages directory '%s' exists already.\n",md_dir)
+		os.Exit(1)
+	}
+	common.Mkdir(md_dir)
+	err := doc.GenMarkdownTree(rootCmd, md_dir)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	err = doc.GenReSTTree(rootCmd, md_dir)
+	fmt.Printf("Markdown pages generated in '%s'\n", md_dir)
+}
+
+func WriteRstPages() {
+	rst_dir := "rst_pages"
+	if common.DirExists(rst_dir) {
+		fmt.Printf("Restructured Text pages directory '%s' exists already.\n",rst_dir)
+		os.Exit(1)
+	}
+	common.Mkdir(rst_dir)
+	err := doc.GenReSTTree(rootCmd, rst_dir)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	fmt.Printf("Restructured Text pages generated in '%s'\n", rst_dir)
+}
+
+func MakeDocumentation(cmd *cobra.Command, args []string) {
 	flags := cmd.Flags()
 	api, _  := flags.GetBool("api")
 	show_hidden, _  := flags.GetBool("show-hidden")
+	bash_completion, _  := flags.GetBool("bash-completion")
+	man_pages, _  := flags.GetBool("man-pages")
+	md_pages, _  := flags.GetBool("markdown-pages")
+	rst_pages, _  := flags.GetBool("rst-pages")
+	if (man_pages && api) || (api && bash_completion) || (api && md_pages) || (api && rst_pages) {
+		fmt.Printf("Choose one option only\n")
+		os.Exit(1)
+	}
+	if rst_pages {
+		WriteRstPages()
+		return
+	}
+	if man_pages {
+		WriteManPages()
+		return
+	}
+	if md_pages {
+		WriteMarkdownPages()
+		return
+	}
+	if bash_completion {
+		WriteBashCompletion()
+		return
+	}
 	if api {
-		fmt.Println("This is the list of commands and modifiers available for dbdeployer")
-		fmt.Println("")
-		fmt.Println("{{dbdeployer --version}}")
-		fmt.Println("# main")
-		fmt.Println("{{dbdeployer -h }}")
-		fmt.Println("")
-		fmt.Println("{{dbdeployer tree }}")
+		WriteApi(show_hidden)
+		return
 	}
 	traverse(rootCmd, "", 0, api, show_hidden)
 }
@@ -66,15 +158,20 @@ func traverse(cmd *cobra.Command, parent string, level int, api, show_hidden boo
 
 var treeCmd = &cobra.Command{
 	Use:   "tree",
-	Short: "shows command tree",
+	Short: "shows command tree and other docs",
+	Aliases: []string{"docs"},
 	Long: `This command is only used to create API documentation. 
 You can, however, use it to show the command structure at a glance.`,
 	Hidden : true,
-	Run: ShowTree,
+	Run: MakeDocumentation,
 }
 
 func init() {
 	rootCmd.AddCommand(treeCmd)
+	treeCmd.PersistentFlags().Bool("man-pages", false, "Writes man pages")
+	treeCmd.PersistentFlags().Bool("markdown-pages", false, "Writes Markdown docs")
+	treeCmd.PersistentFlags().Bool("rst-pages", false, "Writes Restructured Text docs")
 	treeCmd.PersistentFlags().Bool("api", false, "Writes API template")
+	treeCmd.PersistentFlags().Bool("bash-completion", false, "creates bash-completion file")
 	treeCmd.PersistentFlags().Bool("show-hidden", false, "Shows also hidden commands")
 }

common/version.go

@@ -15,7 +15,7 @@
 
 package common
 
-var VersionDef string = "1.1.0" // 2018-03-29
+var VersionDef string = "1.1.1" // 2018-04-02
 
 // Compatible version is the version used to mark compatible archives (templates, configuration).
 // It is usually major.minor.0, except when we are at version 0.x, when