Merge pull request #345 from Vyrastas/master

Documentation Style Guide update and improved Copybara support

Author: Vyrastas

doc/STYLE_GUIDE.md

@@ -11,7 +11,29 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md) for general information on contributin
 
 ## Location
 
-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.
+Place all documentation contributions in the appropriate location in the [`/doc`](./) directory. Most contributions should go into the `/doc/guides` subdirectory, which covers conceptual and usage content, to align it with the structure of the openweave.io documentation site.
+
+Current documentation structure:
+
+Directory | Description
+----|----
+`/doc/guides` | Conceptual or usage content that doesn't fit within a subdirectory, and high-level tutorials
+`/doc/guides/images` | All images included in guide content
+`/doc/guides/profiles` | Content describing or illustrating use of OpenWeave profiles
+`/doc/guides/test` | Content related to testing Weave with Happy
+`/doc/guides/tools` | Content describing or illustrating use of OpenWeave tools
+`/doc/guides/weave-primer` | Weave Primer content
+`/doc/images` | Top-level OpenWeave images, such as logos
+`/doc/presentations` | PDF presentations on Weave features
+`/doc/specs` | PDFs of Weave specifications
+
+If you are unsure of the best location for your contribution, create an Issue and ask, or let us know in your Pull Request.
+
+### Updating the site menus
+
+When adding a new document, or moving one, also update the `_toc.yaml` file(s) in the related folders. For example, the `/doc/guides/tools/_toc.yaml` file is the menu for the [Tools section on openweave.io](https://openweave.io/guides/tools).
+
+New documents should be added to the site menu TOCs where appropriate. If you are unsure of where to place a document within the menu, let us know in your Pull Request.
 
 ## Style
 
@@ -31,6 +53,12 @@ Use standard Markdown when authoring OpenWeave documentation. While HTML may be
 
 > Note: Edit this file to see the Markdown behind the examples.
 
+### Headers
+
+The document title should be an h1 header (#) and in title case (all words are capitalized). All section headers should be h2 (##) or lower and in sentence case (only the first word and proper nouns are capitalized).
+
+The best practice for document clarity is to not go lower than h3, but h4 is fine on occasion. Try to avoid using h4 often, or going lower than h4. If this happens, the document should be reorganized or broken up to ensure it stays at h3 with the occasional h4.
+
 ### Command line examples
 
 Feel free to use either `$` or `%` to preface command line examples, but be consistent within the same doc or set of docs:
@@ -68,29 +96,46 @@ weave-device-mgr (18B4300000000004 @ fd00:0:fab1:6:1ab4:3000:0:4) > ping
 
 ### Commands and output
 
-All example commands and output should be in code blocks with backticks or indented:
+All example commands and output should be in code blocks with backticks:
 
 ```
 code in backticks
 ```
 
+...unless the code is within a step list. In a step list, indent the code blocks:
+
     code indented
 
 ### Code blocks in step lists
 
 When writing procedures that feature code blocks, indent the content for the code blocks:
 
-1.	Step one.
+1.	Step one:
 
         $ git clone https://github.com/openweave/openweave-core.git
         $ cd openweave-core
 
-    More about step one.
+1.  Step two, do something else:
+
+        $ ./configure
+
+For clarity in instructions, avoid putting additional step commands after a code sample
+within a step item. Instead rewrite the instruction so this is not necessary.
+
+For example, avoid this:
 
-1.  Step two, do something else.
+1.  Step three, do this now:
 
         $ ./configure
 
+    And then you will see that thing.
+
+Instead, do this:
+
+1.  Step three, do this now, and you will see that thing:
+
+		$ ./configure
+
 ### Inline code
 
 Use backticks for `inline code`. This includes file paths and file or binary names.
@@ -131,3 +176,36 @@ For example:
 Or:
 
 > Caution: The user should be careful running the next command.
+
+### Material icons
+
+The openweave.io documentation site uses various Material icons inline with the text or in
+diagrams to represent elements of the Weave system. These icons are used to aid in your
+understanding of Weave by highlighting common elements and are not official Weave-branded
+icons.
+
+> You are not required to use these icons, but we may ask to insert them during the review
+process, in order to visually tie concepts together across the documentation site.
+
+Example: https://openweave.io/guides/tools#weave-heartbeat
+
+To use these icons in your content, so that they render on the openweave.io documentation site,
+surround one of the supported keywords with an underscore+asterisk combo.
+
+For example:
+
+<div>_*Echo*_</div>
+<div>_*heartbeat*_</div>
+
+The keyword can be upper or lowercase. Use of this format with unsupported keywords merely
+renders the text in italics.
+
+See the **OpenWeave Tools** page for an example of this:
+
+*   [GitHub version](./guides/tools/index.md)
+*   [openweave.io version](https://openweave.io/guides/tools)
+
+Supported keywords:
+
+*	Echo
+*	Heartbeat

doc/guides/_toc.yaml

@@ -0,0 +1,34 @@
+toc:
+- title: Get Started
+  path: /guides/
+- heading: Weave Primer
+- title: What is Weave?
+  path: /guides/weave-primer/
+  step_group: weave_primer
+- title: Overview
+  path: /guides/weave-primer/overview
+  step_group: weave_primer
+- title: Fabric
+  path: /guides/weave-primer/fabric
+  step_group: weave_primer
+- title: Messaging
+  path: /guides/weave-primer/messaging
+  step_group: weave_primer
+- title: Profiles
+  path: /guides/weave-primer/profiles
+  step_group: weave_primer
+- title: Schema
+  path: /guides/weave-primer/schema
+  step_group: weave_primer
+- title: Data Management
+  path: /guides/weave-primer/data-management
+  step_group: weave_primer
+- heading: Reference
+- title: Glossary
+  path: /guides/glossary
+- heading: Codelabs and Tutorials
+- title: Getting Started with Happy
+  status: external
+  path: https://codelabs.developers.google.com/codelabs/happy-weave-getting-started/#0
+- title: Cross Network Multicast Inet Layer HOWTO
+  path: /guides/cross-network-inet-multicast-howto

doc/guides/test/_toc.yaml

@@ -0,0 +1,3 @@
+toc:
+- title: Test Cases
+  path: /guides/test/

doc/guides/test/index.md

@@ -31,11 +31,11 @@ OpenWeave test cases run against the sample Happy topologies found in
 [`/src/test-apps/happy/topologies/standalone`](https://github.com/openweave/openweave-core/tree/master/src/test-apps/happy/topologies/standalone).
 To use your own custom Happy topology in a test case:
 
-1.  After constructing your custom topology, save it in JSON format:
+1.  After constructing your custom topology, save it in JSON format. This saves
+    the topology state file in the `$HOME` directory:
 
         $ happy-state -s my_topology.json
 
-    This saves the topology state file in the `$HOME` directory.
 1.  In the test case script, locate the topology file being used. Topologies in
     test cases are typically assigned to the `self.topology_file` variable. For
     example,

doc/guides/tools/_toc.yaml

@@ -0,0 +1,7 @@
+toc:
+- title: Overview
+  path: /guides/tools/
+- title: Device Manager
+  path: /guides/tools/device-manager
+- title: Factory Provisioning Tool
+  path: /guides/tools/factory-provisioning-tool

doc/guides/tools/device-manager.md

@@ -83,7 +83,7 @@ $ happy-shell node01
 
 In `node01`, bring up a mock device using that node's Weave IPv6 address and a
 valid Weave pairing code. A pairing code is required to establish a secure
-[PASE](../glossary.md#pase) session between the mock device and Device
+[PASE](/guides/glossary.md#pase) session between the mock device and Device
 Manager:
 
 ```
@@ -187,8 +187,6 @@ weave-device-mgr (18B4300000000004 @ fd00:0:fab1:6:1ab4:3000:0:4) >
 The output on the mock device (`node01`), confirms a successful connection:
 
 ```
-### node01 - mock device
-
 WEAVE:EM: Msg rcvd 0000000E:1 16 0000000000000001 0000 986B 0 MsgId:23C64568
 WEAVE:EM: ec id: 1, AppState: 0x3aadf480
 IdentifyRequest received from node 1 (fd00:0:fab1:6:1ab4:3000:0:5)
@@ -230,8 +228,6 @@ Ping complete
 Output on the mock device (`node01`) confirms the successful Echo:
 
 ```
-### node01 - mock device
-
 WEAVE:EM: Msg rcvd 00000001:1 0 0000000000000001 3960 986F 0 MsgId:00000000
 WEAVE:EM: ec id: 1, AppState: 0x3aadfbb0
 WEAVE:SM: Reserve session key: Id=2CFF Peer=0000000000000001 Reserve=1