Skip to content
This repository was archived by the owner on Dec 20, 2023. It is now read-only.

Commit 5568287

Browse files
authored
Merge pull request #267 from Vyrastas/master
Add documentation style guide
2 parents 638e7f1 + 4068fa2 commit 5568287

File tree

3 files changed

+142
-20
lines changed

3 files changed

+142
-20
lines changed

CONTRIBUTING.md

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Contributing to openweave
1+
Contributing to OpenWeave
22
========================
33

44
Want to contribute? Great! First, read this page (including the small
@@ -28,10 +28,19 @@ avoid frustration later on.
2828
All submissions, including submissions by project members, require
2929
review. We use Github pull requests for this purpose.
3030

31+
### Documentation ###
32+
33+
Documentation undergoes the same review process as code and
34+
contributions may be mirrored on our [openweave.io][ow-io] website.
35+
See the [Documentation Style Guide][doc-style] for more information on
36+
how to author and format documentation for contribution.
37+
3138
### The small print ###
3239

3340
Contributions made by corporations are covered by a different
3441
agreement than the one above, the [Software Grant and Corporate
3542
Contributor License Agreement][CLA-CORP].
3643

3744
[CLA-CORP]: https://cla.developers.google.com/about/google-corporate
45+
[doc-style]: /doc/STYLE_GUIDE.md
46+
[ow-io]: https://openweave.io

doc/STYLE_GUIDE.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# OpenWeave Documentation Style Guide
2+
3+
OpenWeave documentation lives in two locations:
4+
5+
* **GitHub** — All guides and tutorials across the complete [OpenWeave organization](https://github/openweave).
6+
* **openweave.io** - OpenWeave news and features, educational material, API reference, and all guides and tutorials found on GitHub.
7+
8+
All documentation contributions are done on GitHub and mirrored on [openweave.io](https://openweave.io), and will be reviewed for clarity, accuracy, spelling, and grammar prior to acceptance.
9+
10+
See [CONTRIBUTING.md](../CONTRIBUTING.md) for general information on contributing to this project.
11+
12+
## Location
13+
14+
Place all documentation contributions in the appropriate location in the [`/doc`](./) directory. If you are unsure of the best location for your contribution, let us know in your pull request.
15+
16+
## Style
17+
18+
OpenWeave follows the [Google Developers Style Guide](https://developers.google.com/style/). See the [Highlights](https://developers.google.com/style/highlights) page for a quick overview.
19+
20+
## Markdown guidelines
21+
22+
Use standard Markdown when authoring OpenWeave documentation. While HTML may be used for more complex content such as tables, use Markdown as much as possible. To ease mirroring and to keep formatting consistent with openweave.io, we ask that you follow the specific guidelines listed here.
23+
24+
> Note: Edit this file to see the Markdown behind the examples.
25+
26+
### Command line examples
27+
28+
Feel free to use either `$` or `%` to preface command line examples, but be consistent within the same doc or set of docs:
29+
30+
```
31+
$ git clone https://github.com/openweave/openweave-core.git
32+
% git clone https://github.com/openweave/openweave-core.git
33+
```
34+
35+
### Terminal prompts
36+
37+
If you need use a full terminal prompt with username and hostname, use the format of `root@{hostname}{special-characters}#`.
38+
39+
For example, when logged into a Docker container, you might have a prompt like this:
40+
```
41+
root@c0f3912a74ff:/#
42+
```
43+
44+
Or in a Happy node, you might have:
45+
```
46+
root@BorderRouter:#
47+
```
48+
49+
### Commands and output
50+
51+
All example commands and output should be in code blocks with backticks or indented:
52+
53+
```
54+
code in backticks
55+
```
56+
57+
code indented
58+
59+
### Code blocks in step lists
60+
61+
When writing procedures that feature code blocks, indent the content for the code blocks:
62+
63+
1. Step one.
64+
65+
$ git clone https://github.com/openweave/openweave-core.git
66+
$ cd openweave-core
67+
68+
More about step one.
69+
70+
1. Step two, do something else.
71+
72+
$ ./configure
73+
74+
### Inline code
75+
76+
Use backticks for `inline code`. This includes file paths and file or binary names.
77+
78+
### Replaceable variables
79+
80+
In code examples, denote a replaceable variable with curly braces:
81+
82+
```
83+
--with-weave-inet-project-includes={directory}
84+
```
85+
86+
### Step header numbers
87+
88+
If you want your headers to render with nice-looking step numbers on openweave.io, use level 2 Markdown headers in this format:
89+
90+
## Step 1: Text of the step
91+
## Step 2: Text of the next step
92+
## Step 3: Text of the last step
93+
94+
See the **OpenWeave + Happy Cross Network Multicast Inet Layer HOWTO** for an example of this:
95+
96+
* [GitHub version](./guides/cross-network-inet-multicast-howto.md)
97+
* [openweave.io version](https://openweave.io/guides/cross-network-inet-multicast-howto)
98+
99+
### Callouts
100+
101+
Use a blockquote `>` with one of these callout types:
102+
103+
* Note
104+
* Caution
105+
* Warning
106+
107+
For example:
108+
109+
> Note: This is something to be aware of.
110+
111+
Or:
112+
113+
> Caution: The user should be careful running the next command.

doc/howto/cross-network-inet-multicast-howto.md renamed to doc/guides/cross-network-inet-multicast-howto.md

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22

33
You have decided that you would like to experiment with cross-network multicast using OpenWeave. This how-to guide illustrates using the Happy network simulation tool to set up a virtual topology that demonstrates using OpenWeave's Inet layer across two distinct networks with a multicast proxy.
44

5-
## Step 1: Download and Build mcproxy
5+
## Step 1: Download and build mcproxy
66

7-
The IPv6 multicast proxy daemon, _mcproxy_, serves to proxy / forward / route IPv6 multicast traffic across two disjoint IPv6 network links.
7+
The IPv6 multicast proxy daemon, `mcproxy`, serves to proxy / forward / route IPv6 multicast traffic across two disjoint IPv6 network links.
88

9-
While it is not particularly important where you clone and build the _mcproxy_ daemon executable, please take note of the location where you create it as a relative or absolute path to it will be necessary in Step 6 below.
9+
While it is not particularly important where you clone and build the `mcproxy` daemon executable, please take note of the location where you create it as a relative or absolute path to it is necessary in Step 6 below.
1010

1111
```
1212
% git clone https://github.com/mcproxy/mcproxy.git mcproxy
@@ -16,7 +16,7 @@ While it is not particularly important where you clone and build the _mcproxy_ d
1616
% make
1717
```
1818

19-
## Step 2: Download, Build, and Install happy
19+
## Step 2: Download, build, and install happy
2020

2121
```
2222
% git clone https://github.com/openweave/happy.git happy
@@ -25,7 +25,7 @@ While it is not particularly important where you clone and build the _mcproxy_ d
2525
% sudo make install
2626
```
2727

28-
## Step 3: Download and Build openweave-core
28+
## Step 3: Download and build openweave-core
2929

3030
```
3131
% git clone https://github.com/openweave/openweave-core.git openweave-core
@@ -34,7 +34,7 @@ While it is not particularly important where you clone and build the _mcproxy_ d
3434
% make
3535
```
3636

37-
## Step 4: Establish the Happy Topology
37+
## Step 4: Establish the Happy topology
3838

3939
This creates a topology very similar to the [Happy Codelab](https://codelabs.developers.google.com/codelabs/happy-weave-getting-started/#0).
4040

@@ -56,11 +56,11 @@ This creates a topology very similar to the [Happy Codelab](https://codelabs.dev
5656
% happy-network-route --prefix 192.168.1.0 WiFiNetwork BorderRouter
5757
```
5858

59-
## Step 5: Create the mcproxy Configuration for the Happy Topology
59+
## Step 5: Create the mcproxy configuration for the Happy topology
6060

6161
This creates an IPv6 multicast proxy configuration between the simulated "Thread" network interface on "wpan0" and the simulated "WiFi" network interface on "wlan0" in the Happy topology we created above in Step 4.
6262

63-
While it is not particularly important where you create the _mcproxy.conf_ file, please take note of the location where you create it as a relative or absolute path to it will be necessary in Step 6 below.
63+
While it is not particularly important where you create the `mcproxy.conf` file, please take note of the location where you create it as a relative or absolute path to it is necessary in Step 6.
6464

6565
```
6666
% cat > mcproxy.conf << EOF
@@ -69,41 +69,43 @@ pinstance myProxy: wpan0 ==> wlan0;
6969
EOF
7070
```
7171

72-
## Step 6: Run the Demonstration
72+
## Step 6: Run the demonstration
7373

74-
This will run the IPv6 multicast proxy, _mcproxy_, on the "BorderRouter" node and then will launch the Inet layer multicast functional test sender and receiver on the simulated "Thread" and "WiFi" nodes, respectively.
74+
This runs the IPv6 multicast proxy, `mcproxy`, on the "BorderRouter" node and then launches the Inet layer multicast functional test sender and receiver on the simulated "Thread" and "WiFi" nodes, respectively.
7575

7676
If you'd like, you can transpose the sender and the receiver nodes and the example will work equally as well.
7777

7878
Each of the following sets of commands should be run from parallel, independent shells.
7979

80-
### Border Router
80+
### Border router
8181

8282
```
8383
% happy-shell BorderRouter
84-
$ <absolute or relative path to mcproxy daemon executable from Step 1>/mcproxy -f <absolute or relative path to mcproxy configuration file from Step 5>/mcproxy.conf
84+
root@BorderRouter:# {path-to-mcproxy-from-step1}/mcproxy -f {path-to-mcproxy-config-from-step5}/mcproxy.conf
8585
```
8686

8787
### Receiver
8888

8989
```
9090
% happy-shell WiFiNode
91-
$ openweave-core/src/test-apps/TestInetLayerMulticast -6 --udp -I wlan0 -g 5 --group-expected-rx-packets 5 --group-expected-tx-packets 0 -l
91+
root@WiFiNode:# openweave-core/src/test-apps/TestInetLayerMulticast -6 --udp -I wlan0 -g 5 --group-expected-rx-packets 5 --group-expected-tx-packets 0 -l
9292
```
9393

9494
### Sender
9595

9696
```
9797
% happy-shell ThreadNode
98-
$ openweave-core/src/test-apps/TestInetLayerMulticast -6 --udp -I wpan0 -g 5 --group-expected-rx-packets 0 --group-expected-tx-packets 5 -L
98+
root@ThreadNode:# openweave-core/src/test-apps/TestInetLayerMulticast -6 --udp -I wpan0 -g 5 --group-expected-rx-packets 0 --group-expected-tx-packets 5 -L
9999
```
100100

101-
### Output[^1]
101+
### Output
102+
103+
> Note: Your output may vary slightly around the process IDs and source addresses displayed by the receiver.
102104
103105
#### Sender
104106

105107
```
106-
$ openweave-core/src/test-apps/TestInetLayerMulticast -6 --udp -I wlan0 -g 5 ... -L
108+
% openweave-core/src/test-apps/TestInetLayerMulticast -6 --udp -I wlan0 -g 5 ... -L
107109
Weave Node ready to service events; PID: 50845; PPID: 46482
108110
Using UDP/IPv6, device interface: wpan0 (w/o LwIP)
109111
Will join multicast group ff15::5
@@ -122,7 +124,7 @@ WEAVE:IN: Async DNS worker thread exiting.
122124
#### Receiver
123125

124126
```
125-
$ openweave-core/src/test-apps/TestInetLayerMulticast -6 --udp -I wlan0 -g 5 ... -l
127+
% openweave-core/src/test-apps/TestInetLayerMulticast -6 --udp -I wlan0 -g 5 ... -l
126128
Weave Node ready to service events; PID: 50826; PPID: 46499
127129
Using UDP/IPv6, device interface: wlan0 (w/o LwIP)
128130
Will join multicast group ff15::5
@@ -143,5 +145,3 @@ WEAVE:IN: Async DNS worker thread exiting.
143145
WEAVE:IN: Async DNS worker thread woke up.
144146
WEAVE:IN: Async DNS worker thread exiting.
145147
```
146-
147-
[^1]: Your output may vary slightly around the process IDs and source addresses displayed by the receiver.

0 commit comments

Comments
 (0)