Merge pull request #201 from lets-cli/update-docs-n-small-fixess

update docs and small fixes

cmd/subcommand.go

@@ -11,6 +11,10 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const (
+	shortLimit = 120
+)
+
 // cut all elements before command name.
 func prepareArgs(cmdName string, originalArgs []string) []string {
 	nameIdx := 0
@@ -24,11 +28,23 @@ func prepareArgs(cmdName string, originalArgs []string) []string {
 	return originalArgs[nameIdx:]
 }
 
+func short(text string) string {
+	if idx := strings.Index(text, "\n"); idx >= 0 {
+		return text[:idx]
+	}
+
+	if len(text) > shortLimit {
+		return text[:shortLimit]
+	}
+
+	return text
+}
+
 // newCmdGeneric creates new cobra root sub command from Command.
 func newCmdGeneric(command config.Command, conf *config.Config, out io.Writer) *cobra.Command {
 	subCmd := &cobra.Command{
 		Use:   command.Name,
-		Short: command.Description,
+		Short: short(command.Description),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			only, exclude, err := parseOnlyAndExclude(cmd)
 			if err != nil {
@@ -48,7 +64,6 @@ func newCmdGeneric(command config.Command, conf *config.Config, out io.Writer) *
 			command.Only = only
 			command.Exclude = exclude
 			command.Args = prepareArgs(command.Name, os.Args)
-			command.CommandArgs = command.Args[1:]
 			command.OverrideEnv = envs
 			// replace only one placeholder in options
 			command.Docopts = strings.Replace(

config/config/command.go

@@ -40,9 +40,6 @@ type Command struct {
 	// args with command name
 	// e.g. from 'lets run --debug' we will get [run, --debug]
 	Args []string
-	// args without command name
-	// e.g. from 'lets run --debug' we will get [--debug]
-	CommandArgs []string
 
 	// run only specified commands from cmd map
 	Only []string
@@ -61,6 +58,16 @@ type Command struct {
 	RefArgs []string
 }
 
+// args without command name
+// e.g. from 'lets run --debug' we will get [--debug].
+func (cmd Command) CommandArgs() []string {
+	if len(cmd.Args) == 0 {
+		return []string{}
+	}
+
+	return cmd.Args[1:]
+}
+
 // NewCommand creates new command struct.
 func NewCommand(name string) Command {
 	return Command{
@@ -86,8 +93,6 @@ func (cmd Command) FromRef(refCommand Command) Command {
 		newCmd.Args = append(newCmd.Args, refCommand.RefArgs...)
 	}
 
-	newCmd.CommandArgs = newCmd.Args[1:]
-
 	return newCmd
 }
 

docs/docs/architecture.md

@@ -53,7 +53,7 @@ Now we have to bind our config to `Cobra`.
 
 Cobra has a concept of `cobra.Command`. It is a representation of command in CLI application, for example:
 
-```shell
+```bash
 git commit
 git pull
 ```

docs/docs/config.md

@@ -3,9 +3,6 @@ id: config
 title: Config reference
 ---
 
-
-Config schema
-
 * [shell](#shell)
 * [mixins](#mixins)
 * [env](#global-env)
@@ -474,7 +471,7 @@ commands:
 
 Running `lets test` will output: 
 
-```shell
+```bash
 # lets test
 # Hi developer
 # Something is happening

docs/docs/development.md

@@ -35,25 +35,25 @@ It will install `lets-dev` to /usr/local/bin/lets-dev, or wherever you`ve specif
 
 To run all tests:
 
-```shell script
+```bash
 lets test
 ```
 
 To run unit tests:
 
-```shell script
+```bash
 lets test-unit
 ```
 
 To get coverage:
 
-```shell script
+```bash
 lets coverage
 ```
 
 To test `lets` output we are using `bats` - bash automated testing:
 
-```shell script
+```bash
 lets test-bats
 
 # or run one test

docs/docs/getting_started.md → docs/docs/quick_start.md

@@ -1,7 +1,7 @@
 ---
-id: getting_started
+id: quick_start
 title: Getting started with Lets
-sidebar_label: Getting started with Lets
+sidebar_label: Quick start
 ---
 
 If you already have `lets.yaml` then just go to that directory and run `lets` to see all available commands.
@@ -37,21 +37,20 @@ lets # it will use lets.yaml right here (at /home/me/project/lets.yaml)
 shell: /bin/sh
 
 commands:
-    echo:
-      description: Echo text
-      cmd: |
-        echo "Hello"
-    
-    run:
-      description: Run some command
-      options: |
-        Usage: lets run [--debug] [--level=<level>]
-        
-        Options:
-          --debug, -d     Run with debug
-          --level=<level> Log level
-      cmd: |
-        env
+  echo:
+    description: Echo text
+    cmd: |
+      echo "Hello"
+      echo "World"
+
+  run:
+    description: Run some command
+    options: |
+      Usage: lets run [--debug] [--level=<level>]
+      Options:
+        --debug, -d     Run with debug
+        --level=<level> Log level
+    cmd: env
 ```
 
 3. Run commands

docs/docs/what_is_lets.md

@@ -2,50 +2,65 @@
 id: what_is_lets
 title: What is lets ?
 sidebar_label: What is lets ?
+slug: /
 ---
 
-Lets is a task runner.
+### Introduction
+
+`Lets` is a task runner.
 
 You can think of it as a tool with a config where you can write tasks.
 
-The task is usually your set of commands which you can type ten times a day, for example, you want to run tests in your project:
+The task is usually your set of cli commands which you want to group together and gave it a name.
 
-- pull the latest master
-- spinup a database
-- run migrations
-- run tests (maybe run only one test file)
+For example, if you want to run tests in your project you may need to run next commands:
 
-Or some initial setup script for your application:
 
-- docker build -t myapp -f Dockerfile.dev .
-- docker-compose up myapp postgres
+```bash
+# spinup a database for tests
+docker-compose up postgres
+# apply database migrations
+docker-compose run --rm sql alembic upgrdade head
+# run some tets
+docker-compose run --rm app pytest -x "test_login"
+```
 
-This all can be represented in the task.
+This all can be represented in one task - for example `lets test`
 
-So is there are any of such tools out there ? 
+```yaml
+command:
+  test:
+    description: Run integration tests
+    cmd: |
+      docker-compose up postgres
+      docker-compose run --rm sql alembic upgrdade head
+      docker-compose run --rm app pytest -x "test_login"
+```
 
-Well, sure there are some.
+And execute - `lets test`. Now everyone in you team knows how to run tests.
 
-Many developers know such a tool called Make.
+### Why yet another task runner ?
 
-So why not Make ?
+So is there are any of such tools out there ?
+
+Well, sure there are some.
 
-Make is more like a build tool and was not intended to use as a task runner (but usually used because of the lack of alternatives).
+Many developers know such a tool called `make`.
 
-Make has some sort of things which are bad/hard/no convinient for developers which use task runners on a daily basis.
+So why not `make` ?
 
-Lets is a brand new task runner with a task-centric philosophy and written specifically to meet developers needs.
+`make` is more like a build tool and was not intended to be used as a task runner (but usually used because of the lack of alternatives or because it is install on basicaly every developer's machine).
 
-Lets features:
+`make` has some sort of things which are bad/hard/no convinient for developers which use task runners on a daily basis.
 
-- yaml-based config - human-readable, recognizable and convenient format for such configs (also used by kubernetes, ansible, and many others)
+Lets is a brand new task runner with a task-centric philosophy and created specifically to meet developers needs.
 
-- has support for global env
-- has support for global computed env (known as `eval_env`)
-- has support for per-command env 
-- has support for per-command computed env (known as `eval_env`)
-- has `checksum` support - a feature which helps to track file changes
-- has checksum persistence
-- written in Go - which means it is easy to read, write and test as well as contributing to project
+### Features
 
+- `yaml config` - human-readable, recognizable and convenient format for such configs (also used by kubernetes, ansible, and many others)
+- `global and per/command env`
+- `global and per/command dynamic env` - can be computed at runtime
+- `checksum` - a feature which helps to track file changes
+- `written in Go` - which means it is easy to read, write and test as well as contributing to project
 
+To see all features, [check out config documentation](config.md)

docs/docusaurus.config.js

@@ -7,14 +7,17 @@ module.exports = {
   organizationName: 'lets-cli', // Usually your GitHub org/user name.
   projectName: 'lets', // Usually your repo name.
   themeConfig: {
+    prism: {
+      theme: require('prism-react-renderer/themes/vsDark'),
+    },
     navbar: {
       title: 'Lets',
       logo: {
         alt: 'Lets Logo',
         src: 'img/logo.png',
       },
       items: [
-        {to: 'docs/getting_started', label: 'Getting Started', position: 'right'},
+        {to: 'docs/quick_start', label: 'Docs', position: 'right'},
         {to: 'blog', label: 'Blog', position: 'right'},
         {
           href: 'https://github.com/lets-cli/lets',
@@ -30,8 +33,8 @@ module.exports = {
           title: 'Docs',
           items: [
             {
-              label: 'Getting Started',
-              to: 'docs/getting_started',
+              label: 'Quick start',
+              to: 'docs/quick_start',
             },
           ],
         },
@@ -60,6 +63,11 @@ module.exports = {
       ],
       copyright: `Copyright © ${new Date().getFullYear()} Lets, Inc. Built with Docusaurus.`,
     },
+    // algolia: {
+    //   appId: "",
+    //   apiKey: "",
+    //   indexName: "",
+    // }
   },
   presets: [
     [
@@ -73,6 +81,10 @@ module.exports = {
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
         },
+        gtag: {
+          trackingID: 'G-DLCLPWY8PL',
+          anonymizeIP: true,
+        },
       },
     ],
   ],

docs/sidebars.js

@@ -3,7 +3,7 @@ module.exports = {
     "Introduction": [
       'what_is_lets',
       'installation',
-      'getting_started',
+      'quick_start',
       'completion',
     ],
     "Usage": [

runner/run.go

@@ -228,19 +228,22 @@ func (r *Runner) initCmd() error {
 	return nil
 }
 
+// TODO before works not as intended. maybe mvdan/sh will fix this.
 func joinBeforeAndScript(before string, script string) string {
 	if before == "" {
 		return script
 	}
 
+	before = strings.TrimSpace(before)
+
 	return strings.Join([]string{before, script}, "\n")
 }
 
 // Setup env for cmd.
 func (r *Runner) setupEnv(cmd *exec.Cmd, shell string) {
 	defaultEnv := map[string]string{
 		GenericCmdNameTpl:   r.cmd.Name,
-		"LETS_COMMAND_ARGS": strings.Join(r.cmd.CommandArgs, " "),
+		"LETS_COMMAND_ARGS": strings.Join(r.cmd.CommandArgs(), " "),
 		"SHELL":             shell,
 	}
 
@@ -288,13 +291,16 @@ func (r *Runner) prepareOsCommandForRun(cmdScript string) *exec.Cmd {
 		shell = r.cmd.Shell
 	}
 
+	args := []string{"-c", script}
+	if len(r.cmd.CommandArgs()) > 0 {
+		// for "--" see https://linux.die.net/man/1/bash
+		args = append(args, "--", strings.Join(r.cmd.CommandArgs(), " "))
+	}
+
 	cmd := exec.Command(
 		shell,
-		"-c",
-		script,
-		"--", // see https://linux.die.net/man/1/bash
-		strings.Join(r.cmd.CommandArgs, " "),
-	) // #nosec G204
+		args...,
+	)
 
 	// setup std out and err
 	cmd.Stdout = r.out