Skip to content

[gen-readme] Improve gen readme #1735

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 24, 2024
Merged

[gen-readme] Improve gen readme #1735

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 58 additions & 28 deletions devbox.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,42 @@

Instant, easy, and predictable development environments

## Scripts
## Getting Started
This project uses [devbox](https://github.com/jetpack-io/devbox) to manage its development environment.

Install devbox:
```sh
curl -fsSL https://get.jetpack.io/devbox | bash
```

* [build](#build)
* [build-all](#build-all)
* [build-darwin-amd64](#build-darwin-amd64)
* [build-darwin-arm64](#build-darwin-arm64)
* [build-linux-amd64](#build-linux-amd64)
* [build-linux-arm64](#build-linux-arm64)
* [code](#code)
* [fmt](#fmt)
* [lint](#lint)
* [test](#test)
* [tidy](#tidy)
* [update-examples](#update-examples)

## Init Hook
Start the devbox shell:
```sh
devbox shell
```

Run a script in the devbox environment:
```sh
devbox run <script>
```
## Scripts
Scripts are custom commands that can be run using this project's environment. This project has the following scripts:

* [build](#devbox-run-build)
* [build-all](#devbox-run-build-all)
* [build-darwin-amd64](#devbox-run-build-darwin-amd64)
* [build-darwin-arm64](#devbox-run-build-darwin-arm64)
* [build-linux-amd64](#devbox-run-build-linux-amd64)
* [build-linux-arm64](#devbox-run-build-linux-arm64)
* [code](#devbox-run-code)
* [fmt](#devbox-run-fmt)
* [lint](#devbox-run-lint)
* [test](#devbox-run-test)
* [tidy](#devbox-run-tidy)
* [update-examples](#devbox-run-update-examples)

## Shell Init Hook
The Shell Init Hook is a script that runs whenever the devbox environment is instantiated. It runs
on `devbox shell` and on `devbox run`.
```sh
test -z $FISH_VERSION && unset CGO_ENABLED GO111MODULE GOARCH GOFLAGS GOMOD GOOS GOROOT GOTOOLCHAIN GOWORK
```
Expand All @@ -29,74 +48,85 @@ test -z $FISH_VERSION && unset CGO_ENABLED GO111MODULE GOARCH GOFLAGS GOMOD GOOS
* [go@latest](https://www.nixhub.io/packages/go)
* [runx:golangci/golangci-lint@latest](https://www.github.com/golangci/golangci-lint)
* [runx:mvdan/gofumpt@latest](https://www.github.com/mvdan/gofumpt)
* nixpkgs/63143ac2c9186be6d9da6035fa22620018c85932#hello

## Script Details

### build
### devbox run build
Build devbox for the current platform
```sh
go build -o dist/devbox ./cmd/devbox
```
&ensp;

### build-all
### devbox run build-all
```sh
devbox run build-darwin-amd64
devbox run build-darwin-arm64
devbox run build-linux-amd64
devbox run build-linux-arm64
```
&ensp;

### build-darwin-amd64
### devbox run build-darwin-amd64
```sh
GOOS=darwin GOARCH=amd64 go build -o dist/devbox-darwin-amd64 ./cmd/devbox
```
&ensp;

### build-darwin-arm64
### devbox run build-darwin-arm64
```sh
GOOS=darwin GOARCH=arm64 go build -o dist/devbox-darwin-arm64 ./cmd/devbox
```
&ensp;

### build-linux-amd64
### devbox run build-linux-amd64
```sh
GOOS=linux GOARCH=amd64 go build -o dist/devbox-linux-amd64 ./cmd/devbox
```
&ensp;

### build-linux-arm64
### devbox run build-linux-arm64
```sh
GOOS=linux GOARCH=arm64 go build -o dist/devbox-linux-arm64 ./cmd/devbox
```
&ensp;

### code
### devbox run code
Open VSCode
```sh
code .
```
&ensp;

### fmt
### devbox run fmt
```sh
scripts/gofumpt.sh
```
&ensp;

### lint
### devbox run lint
```sh
golangci-lint run --timeout 5m && scripts/gofumpt.sh
```
&ensp;

### test
### devbox run test
```sh
go test -race -cover ./...
```
&ensp;

### tidy
### devbox run tidy
```sh
go mod tidy
```
&ensp;

### update-examples
### devbox run update-examples
```sh
devbox run build && go run testscripts/testrunner/updater/main.go
```
&ensp;



Expand Down
28 changes: 24 additions & 4 deletions internal/devbox/docgen/readme.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,29 @@
{{- if .Description }}
{{ .Description }}
{{ end }}
## Getting Started
This project uses [devbox](https://github.com/jetpack-io/devbox) to manage its development environment.

Install devbox:
```sh
curl -fsSL https://get.jetpack.io/devbox | bash
```

Start the devbox shell:
```sh
devbox shell
```
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WDYT about nudging people towards using direnv as well? It tends to be significantly faster than starting a devbox shell (since we don't start a new shell process)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feels weird to me since I personally don't use it (I tend to use devbox run a lot which is faster than shell).

Feels a bit prescriptive no? i.e. devbox is absolutely needed to develop on this repo, but direnv is more a matter of opinion?

Anyway, a follow up to this could be to allow people to specify their own readme templates so they can modify as needed.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

its just sooo much faster


Run a script in the devbox environment:
```sh
devbox run <script>
```

{{- if .Scripts }}
## Scripts
Scripts are custom commands that can be run using this project's environment. This project has the following scripts:
{{ range $name, $_ := .Scripts }}
* [{{ $name }}](#{{ $name }})
* [{{ $name }}](#devbox-run-{{ $name }})
{{- end }}
{{ end }}

Expand All @@ -26,8 +44,9 @@
{{ end }}

{{- if .InitHook }}
## Init Hook

## Shell Init Hook
The Shell Init Hook is a script that runs whenever the devbox environment is instantiated. It runs
on `devbox shell` and on `devbox run`.
```sh
{{ .InitHook }}
```
Expand All @@ -43,13 +62,14 @@
{{- if .Scripts }}
## Script Details
{{ range $name, $commands := .Scripts }}
### {{ $name }}
### devbox run {{ $name }}
{{- if .Comments }}
{{ .Comments }}
{{- end }}
```sh
{{ $commands }}
```
&ensp;
{{ end }}
{{ end }}

Expand Down