[skip changelog] Add CLI documentation (#602)

* added command reference generator

* add mkdocs build

* add GH pages deploy step

* publish docs only when pr is merged

* added arduino logo

* automate grpc docs generation

* improve Taskfile to support local development

* add docs for working on docs, much meta

Author: Massimiliano Pippi

.github/workflows/docs.yaml

@@ -0,0 +1,65 @@
+name: docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'docsgen/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install Taskfile
+        uses: Arduino/actions/setup-taskfile@master
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Go
+        uses: actions/setup-go@v2-beta
+        with:
+          go-version: '1.13'
+
+      - name: Install Go dependencies
+        run: |
+          go version
+          go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
+
+      - name: Install protoc compiler
+        uses: arduino/setup-protoc@v1.1.0
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: '3.6'
+          architecture: 'x64'
+
+      - name: Cache dependencies
+        uses: actions/cache@v1
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install Python dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install -r ./requirements_docs.txt
+
+      - name: Build docs website
+        run: task docs:build
+
+      - name: Deploy
+        # publish docs only when PR is merged
+        if: github.event.pull_request.merged == 'true'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./public

.gitignore

@@ -20,3 +20,9 @@ venv
 
 # Misc.
 .DS_Store
+
+# Mkdocs
+/public/
+/docsgen/arduino-cli
+/docs/rpc/*.md
+/docs/commands/*.md

CONTRIBUTING.md

@@ -22,6 +22,11 @@ If you want to run integration tests you will also need:
 * A serial port with an Arduino device attached
 * A working [Python][3] environment, version 3.5 or later
 
+If you're working on the gRPC interface you will also have to:
+
+* download the [protoc][6] compiler
+* run `go get -U github.com/golang/protobuf/protoc-gen-go`
+
 ## Building the source code
 
 From the project folder root, just run:
@@ -133,6 +138,36 @@ If the last step was successful, you should be able to run the tests with:
 task test-integration
 ```
 
+## Working on docs
+
+Documentation consists of several Markdown files stored under the `docs` folder
+at the root of the repo. Some of those files are automatically generated in the
+CI pipeline that builds the documentation website so you won't find them in the
+git repository and you need to generate them locally.
+
+If you're working on docs and your changes are not trivial, you might want to
+preview the documentation website locally, before opening a Pull Request. To run
+the docs toolchain locally you need to have:
+
+* [Go][1] version 1.12 or later
+* [Taskfile][2] to help you run the most common tasks from the command line
+* A working [Python][3] environment, version 3.5 or later
+
+Before running the toolchain, perform the following operations:
+
+* go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
+
+When working on docs, you can launch a command that will take care of
+generating the docs, build the static website and start a local server you can
+access with your browser to see a preview of your changes - to launch this
+command do:
+
+```shell
+task docs:serve
+```
+
+If you dont' see any error, hit http://127.0.0.1:8000 with your browser.
+
 ## Pull Requests
 
 In order to ease code reviews and have your contributions merged faster, here is
@@ -170,3 +205,4 @@ title with the string **[skip changelog]**
 [3]: https://www.python.org/downloads/
 [4]: https://docs.python.org/3/tutorial/venv.html
 [5]: https://github.com/ofek/hatch
+[6]: https://github.com/protocolbuffers/protobuf/releases

Taskfile.yml

@@ -1,6 +1,46 @@
 version: '2'
 
 tasks:
+  docs:gen:commands:
+    desc: Generate command reference files
+    dir: ./docsgen
+    cmds:
+      # docs will generate examples using os.Args[0] so we need to call
+      # the generator `arduino-cli`
+      - go build -o arduino-cli
+      # we invoke `arduino-cli` like this instead of `./arduino-cli` to remove
+      # the `./` chars from the examples
+      - PATH=. arduino-cli ../docs/commands
+
+  docs:gen:protobuf:
+    desc: Generate markdown contents for protobuffers
+    cmds:
+      - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,commands.md --proto_path=rpc ./rpc/commands/*.proto'
+      - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,monitor.md --proto_path=rpc ./rpc/monitor/*.proto'
+      - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,settings.md --proto_path=rpc ./rpc/settings/*.proto'
+      - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,debug.md --proto_path=rpc ./rpc/debug/*.proto'
+
+  docs:gen:
+    desc: Generate documentation files
+    cmds:
+      - task: docs:gen:commands
+      - task: docs:gen:protobuf
+
+  docs:build:
+    desc: Build documentation website contents
+    deps:
+      - docs:gen:commands
+      - docs:gen:protobuf
+    cmds:
+      - mkdocs build -s
+
+  docs:serve:
+    desc: Run documentation website locally
+    deps:
+      - docs:build
+    cmds:
+      - mkdocs serve
+
   protoc:
     desc: Compile protobuf definitions
     cmds:
@@ -9,6 +49,14 @@ tasks:
       - '{{ default "protoc" .PROTOC_BINARY }} --proto_path=rpc --go_out=plugins=grpc,paths=source_relative:rpc ./rpc/settings/*.proto'
       - '{{ default "protoc" .PROTOC_BINARY }} --proto_path=rpc --go_out=plugins=grpc,paths=source_relative:rpc ./rpc/debug/*.proto'
 
+  protoc:docs:
+    desc: Generate docs for protobuf definitions
+    cmds:
+      - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,commands.md --proto_path=rpc ./rpc/commands/*.proto'
+      - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,monitor.md --proto_path=rpc ./rpc/monitor/*.proto'
+      - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,settings.md --proto_path=rpc ./rpc/settings/*.proto'
+      - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,debug.md --proto_path=rpc ./rpc/debug/*.proto'
+
   build:
     desc: Build the project
     cmds:
@@ -62,21 +110,18 @@ vars:
   # all modules of this project except for "legacy/..." module
   DEFAULT_TARGETS:
     sh: echo `go list ./... | grep -v legacy | tr '\n' ' '`
-
   # build vars
   COMMIT:
     sh: echo ${TRAVIS_COMMIT:-`git log -n 1 --format=%h`}
   LDFLAGS: >
-      -ldflags '-X github.com/arduino/arduino-cli/version.commit={{.COMMIT}}'
-
+    -ldflags '-X github.com/arduino/arduino-cli/version.commit={{.COMMIT}}'
   # test vars
   GOFLAGS: "-timeout 10m -v -coverpkg=./... -covermode=atomic"
   TEST_VERSIONSTRING: "0.0.0-test.preview"
   TEST_COMMIT: "deadbeef"
   TEST_LDFLAGS: >
     -ldflags  '-X github.com/arduino/arduino-cli/version.versionString={{.TEST_VERSIONSTRING}}
     -X github.com/arduino/arduino-cli/version.commit={{.TEST_COMMIT}}'
-
   # check-lint vars
   GOLINTBIN:
     sh: go list -f {{"{{"}}".Target{{"}}"}}" golang.org/x/lint/golint