97 lines
3.1 KiB
Markdown
97 lines
3.1 KiB
Markdown
# Go by Example
|
|
|
|
Content and build toolchain for [Go by Example](https://gobyexample.com),
|
|
a site that teaches Go via annotated example programs.
|
|
|
|
### Overview
|
|
|
|
The Go by Example site is built by extracting code and
|
|
comments from source files in `examples` and rendering
|
|
them via the `templates` into a static `public`
|
|
directory. The programs implementing this build process
|
|
are in `tools`, along with dependencies specified in
|
|
the `go.mod`file.
|
|
|
|
The built `public` directory can be served by any
|
|
static content system. The production site uses S3 and
|
|
CloudFront, for example.
|
|
|
|
### Building
|
|
|
|
[](https://github.com/mmcgrana/gobyexample/actions)
|
|
|
|
To build the site you'll need Go installed. Run:
|
|
|
|
```console
|
|
$ tools/build
|
|
```
|
|
|
|
To build continuously in a loop:
|
|
|
|
```console
|
|
$ tools/build-loop
|
|
```
|
|
|
|
To see the site locally:
|
|
|
|
```
|
|
$ tools/serve
|
|
```
|
|
|
|
and open `http://127.0.0.1:8000/` in your browser.
|
|
|
|
### Publishing
|
|
|
|
To upload the site:
|
|
|
|
```console
|
|
$ export AWS_ACCESS_KEY_ID=...
|
|
$ export AWS_SECRET_ACCESS_KEY=...
|
|
$ tools/upload
|
|
```
|
|
|
|
### License
|
|
|
|
This work is copyright Mark McGranaghan and licensed under a
|
|
[Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/).
|
|
|
|
The Go Gopher is copyright [Renée French](http://reneefrench.blogspot.com/) and licensed under a
|
|
[Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/).
|
|
|
|
|
|
### Translations
|
|
|
|
Contributor translations of the Go by Example site are available in:
|
|
|
|
* [Chinese](https://gobyexample-cn.github.io/) by [gobyexample-cn](https://github.com/gobyexample-cn)
|
|
* [Czech](http://gobyexamples.sweb.cz/) by [martinkunc](https://github.com/martinkunc/gobyexample-cz)
|
|
* [French](http://le-go-par-l-exemple.keiruaprod.fr) by [keirua](https://github.com/keirua/gobyexample)
|
|
* [Italian](http://gobyexample.it) by the [Go Italian community](https://github.com/golangit/gobyexample-it)
|
|
* [Japanese](http://spinute.org/go-by-example) by [spinute](https://github.com/spinute)
|
|
* [Korean](https://mingrammer.com/gobyexample/) by [mingrammer](https://github.com/mingrammer)
|
|
* [Russian](https://gobyexample.com.ru/) by [badkaktus](https://github.com/badkaktus)
|
|
* [Spanish](http://goconejemplos.com) by the [Go Mexico community](https://github.com/dabit/gobyexample)
|
|
* [Ukrainian](http://butuzov.github.io/gobyexample/) by [butuzov](https://github.com/butuzov/gobyexample)
|
|
|
|
### Thanks
|
|
|
|
Thanks to [Jeremy Ashkenas](https://github.com/jashkenas)
|
|
for [Docco](http://jashkenas.github.io/docco/), which
|
|
inspired this project.
|
|
|
|
### FAQ
|
|
|
|
#### I'm getting output in a different order from the example. Is the example wrong?
|
|
|
|
Some of the examples demonstrate concurrent code which has a non-deterministic
|
|
execution order. It depends on how the Go runtime schedules its goroutines and
|
|
may vary by operating system, CPU architecture, or even Go version.
|
|
|
|
It doesn't mean anything is wrong with the example. Typically the code in these
|
|
examples will be insensitive to the actual order of the output; if the code is
|
|
sensitive to the order - that's probably a bug - so feel free to report it.
|
|
|
|
|
|
|
|
|