Skip to content

Commit fdd87a8

Browse files
benolayinkabenolayinka
committed
doc: Create docs
1 parent aae46c3 commit fdd87a8

98 files changed

Lines changed: 14002 additions & 4 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.editorconfig‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
root = true
2+
3+
[*]
4+
max_line_length = 300
5+
indent_style = space
6+
indent_size = 2
7+
end_of_line = lf
8+
insert_final_newline = true
9+
trim_trailing_whitespace = true
10+
charset = utf-8
11+
12+
[*.go]
13+
indent_style = tab
14+
15+
[*.md]
16+
trim_trailing_whitespace = false
17+
18+
[Makefile]
19+
indent_style = tab
20+
indent_size = 2

‎.gitignore‎

Lines changed: 103 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,114 @@
1+
2+
# Created by https://www.gitignore.io/api/macos,linux,windows,go
3+
4+
### Go ###
15
# Binaries for programs and plugins
26
*.exe
3-
*.exe~
47
*.dll
58
*.so
69
*.dylib
710

8-
# Test binary, built with `go test -c`
11+
# Test binary, build with `go test -c`
912
*.test
1013

1114
# Output of the go coverage tool, specifically when used with LiteIDE
1215
*.out
1316

14-
# Dependency directories (remove the comment below to include it)
15-
# vendor/
17+
# Project-local glide cache, RE: https://github.com/Masterminds/glide/issues/736
18+
.glide/
19+
20+
### Linux ###
21+
*~
22+
23+
# temporary files which can be created if a process still has a handle open of a deleted file
24+
.fuse_hidden*
25+
26+
# KDE directory preferences
27+
.directory
28+
29+
# Linux trash folder which might appear on any partition or disk
30+
.Trash-*
31+
32+
# .nfs files are created when an open file is removed but is still being accessed
33+
.nfs*
34+
35+
### macOS ###
36+
*.DS_Store
37+
.AppleDouble
38+
.LSOverride
39+
40+
# Icon must end with two \r
41+
Icon
42+
43+
# Thumbnails
44+
._*
45+
46+
# Files that might appear in the root of a volume
47+
.DocumentRevisions-V100
48+
.fseventsd
49+
.Spotlight-V100
50+
.TemporaryItems
51+
.Trashes
52+
.VolumeIcon.icns
53+
.com.apple.timemachine.donotpresent
54+
55+
# Directories potentially created on remote AFP share
56+
.AppleDB
57+
.AppleDesktop
58+
Network Trash Folder
59+
Temporary Items
60+
.apdisk
61+
62+
### Windows ###
63+
# Windows thumbnail cache files
64+
Thumbs.db
65+
ehthumbs.db
66+
ehthumbs_vista.db
67+
68+
# Folder config file
69+
Desktop.ini
70+
71+
# Recycle Bin used on file shares
72+
$RECYCLE.BIN/
73+
74+
# Windows Installer files
75+
*.cab
76+
*.msi
77+
*.msm
78+
*.msp
79+
80+
# Windows shortcuts
81+
*.lnk
82+
83+
# End of https://www.gitignore.io/api/macos,linux,windows,go
84+
85+
*.coverprofile
86+
/dist
87+
/vendor
88+
/release
89+
/.cache
90+
node_modules/
91+
/sdk/js/dist
92+
/public
93+
/internal
94+
/stories
95+
/pkg/webui/locales/.backend
96+
97+
# Development tooling
98+
/tools/bin/mage
99+
100+
# Keypair
101+
cert.pem
102+
key.pem
103+
ca.pem
104+
105+
# Development data directory
106+
.dev/
107+
.env/
108+
109+
# Javascript test coverage
110+
/coverage
111+
/sdk/js/coverage
112+
113+
# Release files
114+
/snapcraft.login

‎Makefile‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Copyright © 2019 The Things Network Foundation, The Things Industries B.V.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
GO = go
16+
HUGO = $(GO) run -tags extended github.com/gohugoio/hugo
17+
YARN_DEPS = doc/themes/the-things-stack/node_modules
18+
FREQUENCY_PLAN_URL = https://raw.githubusercontent.com/TheThingsNetwork/lorawan-frequency-plans/master/frequency-plans.yml
19+
FREQUENCY_PLAN_DEST = doc/data/frequency-plans.yml
20+
PUBLIC_DEST = public
21+
INTERNAL_DEST = internal
22+
ENVIRONMENT = gh-pages
23+
24+
.PHONY: default
25+
default: build.internal
26+
27+
.PHONY: clean.internal
28+
clean.internal:
29+
rm -rf $(INTERNAL_DEST)
30+
31+
.PHONY: clean.public
32+
clean.public:
33+
rm -rf $(PUBLIC_DEST)
34+
35+
.PHONY: build.internal
36+
build.internal: $(INTERNAL_DEST) deps
37+
$(HUGO) -d $(INTERNAL_DEST)
38+
39+
.PHONY: build.public
40+
build.public: $(PUBLIC_DEST) deps
41+
$(HUGO) -s "./doc" -d $(PUBLIC_DEST) -b $(HUGO_BASE_URL) --environment $(ENVIRONMENT)
42+
43+
.PHONY: server
44+
server: deps
45+
$(HUGO) server -s "./doc" --environment $(ENVIRONMENT)
46+
47+
.PHONY: deps
48+
deps: frequency-plan-deps | $(YARN_DEPS)
49+
50+
.PHONY: frequency-plan-deps
51+
frequency-plan-deps:
52+
curl -o $(FREQUENCY_PLAN_DEST) $(FREQUENCY_PLAN_URL)
53+
54+
$(YARN_DEPS):
55+
@if ! [ -x "$$(command -v yarn)" ]; then\
56+
echo "Installing yarn";\
57+
curl -o- -L https://yarnpkg.com/install.sh | bash;\
58+
fi
59+
yarn --cwd doc/themes/the-things-stack/

‎README.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Lorawan Stack Documentation
2+
3+
The documentation site for The Things Stack is built with [Hugo](https://gohugo.io/documentation/).
4+
All content is stored as Markdown files in `doc/content`.
5+
6+
Data for generated documentation like API and glossary is stored in `doc/data`.
7+
8+
## Development Environment Dependencies
9+
10+
The Things Stack Documentation development tooling uses [Go](https://golang.org/doc/install) and [Yarn](https://yarnpkg.com/en/docs/install).
11+
12+
- Follow [Go's installation guide](https://golang.org/doc/install) to install Go.
13+
- Follow [Yarn's installation guide](https://yarnpkg.com/en/docs/install) to install Yarn.
14+
15+
In order to build the documentation site with the right theme, you need to run
16+
`make deps` from time to time. This will install [Yarn](https://yarnpkg.com/) on Mac and Unix systems if it is not already installed.
17+
18+
>Note: as a workaround for [this](https://github.com/gohugoio/hugo/issues/7083), `make deps` also pulls the latest version of [frequency-plans.yml](https://github.com/TheThingsNetwork/lorawan-frequency-plans/).
19+
20+
## Running a Development Server
21+
22+
You can start a development server with live reloading by running
23+
`make server`. This command will print the address of the server.
24+
25+
## Building the Documentation for Github Pages
26+
27+
The documentation site can be built for Github Pages by running `make build-public`. This will
28+
output the site to `public`.
29+
30+
## Building the Documentation for Internal (Offline) Use
31+
32+
The documentation site can be built for internal (offline) use by running `make build` or `make build-internal`. This will
33+
output the site to `internal`.
34+
35+
## Style Guidelines
36+
37+
Please respect the following guidelines for content in our documentation site. A copy and paste template for creating new documentation can be found [here](doc/content/example-template).
38+
39+
- Use the `{{< new-in-version "3.8.5" >}}` shortcode to tag documentation for features added in a particular version. For documentation that targets `master`, that's the next patch bump, e.g `3.8.x`. For documentation targeting `develop` that's the next minor bump, e.g `3.x.0`.
40+
- The title of a doc page is already rendered by the build system as a h1, don't add an extra one.
41+
- Use title case for headings.
42+
- A documentation page starts with an introduction, and then the first heading. The first paragraph of the introduction is typically a summary of the page. Use a `<!--more-->` to indicate where the summary ends.
43+
- Divide long documents into separate files, each with its own folder and `_index.md`.
44+
- Use the `weight`tag in the [Front Matter](https://gohugo.io/content-management/front-matter/) to manually sort sections if necessary. If not, they will be sorted alphabetically.
45+
- Since the title is a `h1`, everything in the content is at least `h2` (`##`).
46+
- Paragraphs typically consist of at least two sentences.
47+
- Use an empty line between all blocks (headings, paragraphs, lists, ...).
48+
- Prefer text over bullet lists or enumerations. For bullets, use `-`, for enumerations `1.` etc.
49+
- Explicitly call this product "The Things Stack". Not "the stack" etc. You can use the shortcode `{{% tts %}}` which will expand to "The Things Stack".
50+
- Avoid shortening, i.e. write "it is" instead of "it's".
51+
- Write guides as a goal-oriented journey.
52+
- Unless already clear from context, use a clearer term than "user", especially if there are multiple kinds (network operator, gateway owner, application developer, ...).
53+
- The user does not have a gender (so use they/them/their).
54+
- Taking screenshots is done as follows:
55+
- In Chrome: activate the **Developer Tools** and toggle the **Device Toolbar**. In the **Device Toolbar**, select **Laptop with HiDPI screen** (add it if not already there), and click **Capture Screenshot** in the menu on the right.
56+
- In Firefox: enter **Responsive Design Mode**. In the **Device Toolbar**, select "Laptop with HiDPI screen" (add it if not already there) and **Take a screenshot of the viewport**.
57+
- Use `**Strong**` when referring to buttons in the Console.
58+
- Use `>Note:`to add a note.
59+
- Use fenced code blocks with a language:
60+
- `bash` for lists of environment variables: `SOME_ENV="value"`.
61+
- `bash` for CLI examples. Prefix commands with `$ `. Wrap strings with double quotes `""` (except when working with JSON, which already uses double quotes).
62+
- Wrap large CLI output with `<details><summary>Show CLI output</summary> ... output here ... </details>`.
63+
- `yaml` (not `yml`) for YAML. Wrap strings with single quotes `''` (because of frequent Go templates that use double quotes).

‎config/.DS_Store‎

6 KB
Binary file not shown.

‎config/_default/config.toml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# File generated by mage. DO NOT EDIT.
2+
# You can edit the template in config.toml.tmpl
3+
4+
title = "The Things Stack for LoRaWAN"
5+
6+
baseURL = "http://localhost/"
7+
8+
disableKinds = [
9+
"taxonomy",
10+
"taxonomyTerm",
11+
"RSS",
12+
"sitemap",
13+
]
14+
15+
enableGitInfo = true
16+
17+
languageCode = "en-us"
18+
languageName = "English"
19+
20+
theme = "the-things-stack"
21+
22+
pygmentsCodeFences = true
23+
pygmentsUseClasses = true
24+
25+
[params]
26+
description = "The Things Stack for LoRaWAN"
27+
keywords = []
28+
github_repository = "https://github.com/TheThingsNetwork/lorawan-stack-docs"
29+
github_repository_edit = "https://github.com/TheThingsNetwork/lorawan-stack-docs/edit/master/doc/content"
30+
version = "v3.8.5"
31+
32+
[markup]
33+
[markup.goldmark]
34+
[markup.goldmark.renderer]
35+
unsafe = true
36+
37+
[menu]
38+
[[menu.right]]
39+
name = "GitHub"
40+
url = "https://github.com/TheThingsNetwork/lorawan-stack-docs"
41+
weight = 1
42+
43+
[[menu.right]]
44+
name = "Forum"
45+
url = "https://www.thethingsnetwork.org/forum/c/network-and-routing/v3"
46+
weight = 2
47+
48+
[[menu.contributing]]
49+
name = "GitHub"
50+
url = "https://github.com/TheThingsNetwork/lorawan-stack"
51+
weight = 1
52+
53+
[[menu.contributing]]
54+
name = "Forum"
55+
url = "https://www.thethingsnetwork.org/forum/c/network-and-routing/v3"
56+
weight = 2
57+
58+
[[menu.about_us]]
59+
name = "The Things Network"
60+
url = "https://www.thethingsnetwork.org"
61+
weight = 1
62+
63+
[[menu.about_us]]
64+
name = "The Things Industries"
65+
url = "https://www.thethingsindustries.com"
66+
weight = 2

‎config/gh-pages/config.toml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
googleAnalytics = ""
2+
3+
[params]
4+
[params.search]
5+
enabled = false
6+
apikey = ""
7+
index = ""
8+
[params.intercom]
9+
enabled = false
10+
appid = ""
11+
[params.feedback]
12+
enabled = false
13+
campaign = ""

‎content/.DS_Store‎

6 KB
Binary file not shown.

0 commit comments

Comments
 (0)