Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 07e0520

Browse files
author
Massimiliano Pippi
authored
[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
1 parent 4b874a0 commit 07e0520

File tree

14 files changed

+990
-4
lines changed

14 files changed

+990
-4
lines changed

‎.github/workflows/docs.yaml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: docs
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'docs/**'
7+
- 'docsgen/**'
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout
15+
uses: actions/checkout@v2
16+
17+
- name: Install Taskfile
18+
uses: Arduino/actions/setup-taskfile@master
19+
with:
20+
repo-token: ${{ secrets.GITHUB_TOKEN }}
21+
22+
- name: Setup Go
23+
uses: actions/setup-go@v2-beta
24+
with:
25+
go-version: '1.13'
26+
27+
- name: Install Go dependencies
28+
run: |
29+
go version
30+
go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
31+
32+
- name: Install protoc compiler
33+
uses: arduino/setup-protoc@v1.1.0
34+
with:
35+
repo-token: ${{ secrets.GITHUB_TOKEN }}
36+
37+
- name: Setup Python
38+
uses: actions/setup-python@v1
39+
with:
40+
python-version: '3.6'
41+
architecture: 'x64'
42+
43+
- name: Cache dependencies
44+
uses: actions/cache@v1
45+
with:
46+
path: ~/.cache/pip
47+
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
48+
restore-keys: |
49+
${{ runner.os }}-pip-
50+
51+
- name: Install Python dependencies
52+
run: |
53+
python3 -m pip install --upgrade pip
54+
python3 -m pip install -r ./requirements_docs.txt
55+
56+
- name: Build docs website
57+
run: task docs:build
58+
59+
- name: Deploy
60+
# publish docs only when PR is merged
61+
if: github.event.pull_request.merged == 'true'
62+
uses: peaceiris/actions-gh-pages@v3
63+
with:
64+
github_token: ${{ secrets.GITHUB_TOKEN }}
65+
publish_dir: ./public

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,9 @@ venv
2020

2121
# Misc.
2222
.DS_Store
23+
24+
# Mkdocs
25+
/public/
26+
/docsgen/arduino-cli
27+
/docs/rpc/*.md
28+
/docs/commands/*.md

‎CONTRIBUTING.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,11 @@ If you want to run integration tests you will also need:
2222
* A serial port with an Arduino device attached
2323
* A working [Python][3] environment, version 3.5 or later
2424

25+
If you're working on the gRPC interface you will also have to:
26+
27+
* download the [protoc][6] compiler
28+
* run `go get -U github.com/golang/protobuf/protoc-gen-go`
29+
2530
## Building the source code
2631

2732
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:
133138
task test-integration
134139
```
135140

141+
## Working on docs
142+
143+
Documentation consists of several Markdown files stored under the `docs` folder
144+
at the root of the repo. Some of those files are automatically generated in the
145+
CI pipeline that builds the documentation website so you won't find them in the
146+
git repository and you need to generate them locally.
147+
148+
If you're working on docs and your changes are not trivial, you might want to
149+
preview the documentation website locally, before opening a Pull Request. To run
150+
the docs toolchain locally you need to have:
151+
152+
* [Go][1] version 1.12 or later
153+
* [Taskfile][2] to help you run the most common tasks from the command line
154+
* A working [Python][3] environment, version 3.5 or later
155+
156+
Before running the toolchain, perform the following operations:
157+
158+
* go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
159+
160+
When working on docs, you can launch a command that will take care of
161+
generating the docs, build the static website and start a local server you can
162+
access with your browser to see a preview of your changes - to launch this
163+
command do:
164+
165+
```shell
166+
task docs:serve
167+
```
168+
169+
If you dont' see any error, hit http://127.0.0.1:8000 with your browser.
170+
136171
## Pull Requests
137172

138173
In order to ease code reviews and have your contributions merged faster, here is
@@ -170,3 +205,4 @@ title with the string **[skip changelog]**
170205
[3]: https://www.python.org/downloads/
171206
[4]: https://docs.python.org/3/tutorial/venv.html
172207
[5]: https://github.com/ofek/hatch
208+
[6]: https://github.com/protocolbuffers/protobuf/releases

‎Taskfile.yml‎

Lines changed: 49 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,46 @@
11
version: '2'
22

33
tasks:
4+
docs:gen:commands:
5+
desc: Generate command reference files
6+
dir: ./docsgen
7+
cmds:
8+
# docs will generate examples using os.Args[0] so we need to call
9+
# the generator `arduino-cli`
10+
- go build -o arduino-cli
11+
# we invoke `arduino-cli` like this instead of `./arduino-cli` to remove
12+
# the `./` chars from the examples
13+
- PATH=. arduino-cli ../docs/commands
14+
15+
docs:gen:protobuf:
16+
desc: Generate markdown contents for protobuffers
17+
cmds:
18+
- '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,commands.md --proto_path=rpc ./rpc/commands/*.proto'
19+
- '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,monitor.md --proto_path=rpc ./rpc/monitor/*.proto'
20+
- '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,settings.md --proto_path=rpc ./rpc/settings/*.proto'
21+
- '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,debug.md --proto_path=rpc ./rpc/debug/*.proto'
22+
23+
docs:gen:
24+
desc: Generate documentation files
25+
cmds:
26+
- task: docs:gen:commands
27+
- task: docs:gen:protobuf
28+
29+
docs:build:
30+
desc: Build documentation website contents
31+
deps:
32+
- docs:gen:commands
33+
- docs:gen:protobuf
34+
cmds:
35+
- mkdocs build -s
36+
37+
docs:serve:
38+
desc: Run documentation website locally
39+
deps:
40+
- docs:build
41+
cmds:
42+
- mkdocs serve
43+
444
protoc:
545
desc: Compile protobuf definitions
646
cmds:
@@ -9,6 +49,14 @@ tasks:
949
- '{{ default "protoc" .PROTOC_BINARY }} --proto_path=rpc --go_out=plugins=grpc,paths=source_relative:rpc ./rpc/settings/*.proto'
1050
- '{{ default "protoc" .PROTOC_BINARY }} --proto_path=rpc --go_out=plugins=grpc,paths=source_relative:rpc ./rpc/debug/*.proto'
1151

52+
protoc:docs:
53+
desc: Generate docs for protobuf definitions
54+
cmds:
55+
- '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,commands.md --proto_path=rpc ./rpc/commands/*.proto'
56+
- '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,monitor.md --proto_path=rpc ./rpc/monitor/*.proto'
57+
- '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,settings.md --proto_path=rpc ./rpc/settings/*.proto'
58+
- '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,debug.md --proto_path=rpc ./rpc/debug/*.proto'
59+
1260
build:
1361
desc: Build the project
1462
cmds:
@@ -62,21 +110,18 @@ vars:
62110
# all modules of this project except for "legacy/..." module
63111
DEFAULT_TARGETS:
64112
sh: echo `go list ./... | grep -v legacy | tr '\n' ' '`
65-
66113
# build vars
67114
COMMIT:
68115
sh: echo ${TRAVIS_COMMIT:-`git log -n 1 --format=%h`}
69116
LDFLAGS: >
70-
-ldflags '-X github.com/arduino/arduino-cli/version.commit={{.COMMIT}}'
71-
117+
-ldflags '-X github.com/arduino/arduino-cli/version.commit={{.COMMIT}}'
72118
# test vars
73119
GOFLAGS: "-timeout 10m -v -coverpkg=./... -covermode=atomic"
74120
TEST_VERSIONSTRING: "0.0.0-test.preview"
75121
TEST_COMMIT: "deadbeef"
76122
TEST_LDFLAGS: >
77123
-ldflags '-X github.com/arduino/arduino-cli/version.versionString={{.TEST_VERSIONSTRING}}
78124
-X github.com/arduino/arduino-cli/version.commit={{.TEST_COMMIT}}'
79-
80125
# check-lint vars
81126
GOLINTBIN:
82127
sh: go list -f {{"{{"}}".Target{{"}}"}}" golang.org/x/lint/golint

‎docs/commands/.gitkeep‎

Whitespace-only changes.

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /