Bug 1708204 - Apply new structure to book with minimal content changes (#1601)

.gitignore

@@ -1,4 +1,5 @@
 docs/*/book
+docs/*/shared/
 docs/user/appendix/changelog.md
 target
 .cargo

bin/build-rust-docs.sh

@@ -32,6 +32,41 @@ rm -rf build/docs
 mkdir -p build/docs
 echo '<meta http-equiv=refresh content=0;url=book/index.html>' > build/docs/index.html
 
+# Add redirections for all pages moved on the restructuring done on Bug 1708204
+# Android Specific Information
+mkdir -p build/docs/book/user/android/
+echo '<meta http-equiv=refresh content=0;url=../../language-bindings/android/android-build-configuration-options.html>' > build/docs/book/user/android/android-build-configuration-options.html
+echo '<meta http-equiv=refresh content=0;url=../../language-bindings/android/android-offline-builds.html>' > build/docs/book/user/android/android-offline-builds.html
+echo '<meta http-equiv=refresh content=0;url=../language-bindings/android/instrument-android-crashes-example.html>' > build/docs/book/user/instrument-android-crashes-example.html
+echo '<meta http-equiv=refresh content=0;url=../../language-bindings/android/index.html>' > build/docs/book/user/android/index.html
+# General API
+echo '<meta http-equiv=refresh content=0;url=../reference/general/index.html>' > build/docs/book/user/general-api.html
+# Metrics API
+mkdir -p build/docs/book/user/metrics/
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/boolean.html>' > build/docs/book/user/metrics/boolean.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/counter.html>' > build/docs/book/user/metrics/counter.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/custom_distribution.html>' > build/docs/book/user/metrics/custom_distribution.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/datetime.html>' > build/docs/book/user/metrics/datetime.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/event.html>' > build/docs/book/user/metrics/event.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/index.html>' > build/docs/book/user/metrics/index.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/labeled_booleans.html>' > build/docs/book/user/metrics/labeled_booleans.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/labeled_counters.html>' > build/docs/book/user/metrics/labeled_counters.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/labeled_strings.html>' > build/docs/book/user/metrics/labeled_strings.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/memory_distribution.html>' > build/docs/book/user/metrics/memory_distribution.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/quantity.html>' > build/docs/book/user/metrics/quantity.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/rate.html>' > build/docs/book/user/metrics/rate.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/string.html>' > build/docs/book/user/metrics/string.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/string_list.html>' > build/docs/book/user/metrics/string_list.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/timespan.html>' > build/docs/book/user/metrics/timespan.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/timing_distribution.html>' > build/docs/book/user/metrics/timing_distribution.html
+echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/uuid.html>' > build/docs/book/user/metrics/uuid.html
+# YAML Format
+echo '<meta http-equiv=refresh content=0;url=../reference/yaml/index.html>' > build/docs/book/user/metric-parameters.html
+# Metric User Guides
+echo '<meta http-equiv=refresh content=0;url=metrics/adding-new-metrics.html>' > build/docs/book/user/adding-new-metrics.html
+echo '<meta http-equiv=refresh content=0;url=metrics/error-reporting.html>' > build/docs/book/user/error-reporting.html
+echo '<meta http-equiv=refresh content=0;url=metrics/testing-metrics.html>' > build/docs/book/user/testing-metrics.html
+
 mkdir -p build/docs/book
 cp -a docs/user/book/. build/docs/book
 

docs/dev/core/internal/payload.md

@@ -16,7 +16,7 @@ It is written as a set of [templates](https://github.com/mozilla-services/mozill
 
 ### Boolean
 
-A [Boolean](../../../book/user/metrics/boolean.md) is represented by its boolean value.
+A [Boolean](../../../book/reference/metrics/boolean.md) is represented by its boolean value.
 
 #### Example
 
@@ -27,7 +27,7 @@ true
 
 ### Counter
 
-A [Counter](../../../book/user/metrics/counter.md) is represented by its integer value.
+A [Counter](../../../book/reference/metrics/counter.md) is represented by its integer value.
 
 #### Example
 
@@ -37,7 +37,7 @@ A [Counter](../../../book/user/metrics/counter.md) is represented by its integer
 
 ### Quantity
 
-A [Quantity](../../../book/user/metrics/quantity.md) is represented by its integer value.
+A [Quantity](../../../book/reference/metrics/quantity.md) is represented by its integer value.
 
 #### Example
 
@@ -47,7 +47,7 @@ A [Quantity](../../../book/user/metrics/quantity.md) is represented by its integ
 
 ### String
 
-A [String](../../../book/user/metrics/string.md) is represented by its string value.
+A [String](../../../book/reference/metrics/string.md) is represented by its string value.
 
 #### Example
 
@@ -57,7 +57,7 @@ A [String](../../../book/user/metrics/string.md) is represented by its string va
 
 ### String list
 
-A [String List](../../../book/user/metrics/string_list.md) is represented as an array of strings.
+A [String List](../../../book/reference/metrics/string_list.md) is represented as an array of strings.
 
 ```json
 ["sample string", "another one"]
@@ -65,12 +65,12 @@ A [String List](../../../book/user/metrics/string_list.md) is represented as an
 
 ### Timespan
 
-A [Timespan](../../../book/user/metrics/timespan.md) is represented as an object of their duration as an integer and the time unit.
+A [Timespan](../../../book/reference/metrics/timespan.md) is represented as an object of their duration as an integer and the time unit.
 
 | Field name | Type | Description |
 |---|---|---|
 | `value` | Integer | The value in the marked time unit. |
-| `time_unit` | String | The time unit, see the [timespan's configuration](../../../book/user/metrics/timespan.md#configuration) for valid values. |
+| `time_unit` | String | The time unit, see the [timespan's configuration](../../../book/reference/metrics/timespan.md#configuration) for valid values. |
 
 #### Example
 
@@ -83,7 +83,7 @@ A [Timespan](../../../book/user/metrics/timespan.md) is represented as an object
 
 ### Timing Distribution
 
-A [Timing distribution](../../../book/user/metrics/timing_distribution.md) is represented as an object with the following fields.
+A [Timing distribution](../../../book/reference/metrics/timing_distribution.md) is represented as an object with the following fields.
 
 | Field name | Type | Description |
 |---|---|---|
@@ -118,7 +118,7 @@ sent:      1024: 2, 1116: 1, 1217: 0, 1327: 0, 1448: 1, 1579: 0
 
 ### Memory Distribution
 
-A [Memory distribution](../../../book/user/metrics/memory_distribution.md) is represented as an object with the following fields.
+A [Memory distribution](../../../book/reference/metrics/memory_distribution.md) is represented as an object with the following fields.
 
 | Field name | Type | Description |
 |---|---|---|
@@ -142,7 +142,7 @@ See [timing distribution](#timing-distribution) for more details.
 
 ### UUID
 
-A [UUID](../../../book/user/metrics/uuid.md) is represented by the string representation of the UUID.
+A [UUID](../../../book/reference/metrics/uuid.md) is represented by the string representation of the UUID.
 
 #### Example
 
@@ -152,7 +152,7 @@ A [UUID](../../../book/user/metrics/uuid.md) is represented by the string repres
 
 ### Datetime
 
-A [Datetime](../../../book/user/metrics/datetime.md) is represented by its ISO8601 string representation, truncated to the metric's time unit.
+A [Datetime](../../../book/reference/metrics/datetime.md) is represented by its ISO8601 string representation, truncated to the metric's time unit.
 It always includes the timezone offset.
 
 #### Example
@@ -163,7 +163,7 @@ It always includes the timezone offset.
 
 ### Event
 
-[Events](../../../book/user/metrics/event.md) are represented as an array of objects, with one object for each event.
+[Events](../../../book/reference/metrics/event.md) are represented as an array of objects, with one object for each event.
 Each event object has the following keys:
 
 | Field name | Type | Description |
@@ -203,7 +203,7 @@ The maximum timestamp of the events in these pings are quite likely to exceed th
 
 ### Custom Distribution
 
-A [Custom distribution](../../../book/user/metrics/custom_distribution.md) is represented as an object with the following fields.
+A [Custom distribution](../../../book/reference/metrics/custom_distribution.md) is represented as an object with the following fields.
 
 | Field name | Type | Description |
 |---|---|---|
@@ -248,8 +248,8 @@ sent:     10: 0, 12: 2, 14: 0, 17: 0, 19: 0, 22: 1, 24: 0
 
 Currently several labeled metrics are supported:
 
-* [Labeled Counters](../../../book/user/metrics/labeled_counters.md).
-* [Labeled Strings](../../../book/user/metrics/labeled_strings.md).
+* [Labeled Counters](../../../book/reference/metrics/labeled_counters.md).
+* [Labeled Strings](../../../book/reference/metrics/labeled_strings.md).
 
 All are on the top-level represented in the same way, as an object mapping the label to the metric's value.
 See the individual metric types for details on the value payload:
@@ -268,7 +268,7 @@ See the individual metric types for details on the value payload:
 
 ### Rate
 
-A [Rate](../../../book/user/metrics/rate.md) is represented by its `numerator` and `denominator`.
+A [Rate](../../../book/reference/metrics/rate.md) is represented by its `numerator` and `denominator`.
 
 #### Example
 

docs/dev/shared/glean.css

@@ -1,169 +0,0 @@
-/* Style the tab */
-.tabbar {
-    overflow: hidden;
-    border: 1px solid #ccc;
-    background-color: #f1f1f1;
-}
-
-/* Style the buttons that are used to open the tab content */
-.tabbar button {
-    background-color: inherit;
-    float: left;
-    border: none;
-    outline: none;
-    cursor: pointer;
-    padding: 14px 16px;
-    transition: 0.3s;
-}
-
-/* Change background color of buttons on hover */
-.tabbar button:hover {
-    background-color: #ddd;
-}
-
-/* Create an active/current tablink class */
-.tabbar button.active {
-    background-color: #ccc;
-}
-
-/* The container that holds all of the tab contents */
-.tabcontents {
-    display: flex;
-}
-
-/* The container for each individual language */
-.tab {
-    display: none;
-    width: 100%;
-    border: 1px solid #ccc;
-    border-top: none;
-    padding: 6px 12px;
-}
-
-.tab.active {
-    display: block;
-}
-
-/* The footer with the "Open on GitHub" link */
-footer#open-on-gh {
-  font-size: 0.8em;
-  text-align: center;
-  border-top: 1px solid black;
-  padding: 5px 0;
-}
-
-/* Distribution simulator styles */
-
-#simulator-container {
-    display: flex;
-    flex-wrap: wrap;
-    overflow: hidden;
-}
-
-#simulator-container h3 {
-    margin-top: 20px;
-}
-
-#simulator-container .input-group {
-    width: 100%;
-}
-
-#simulator-container .input-group label {
-    display: block;
-    font-weight: bold;
-    font-size: 14px;
-    margin-bottom: 7px;
-}
-
-#simulator-container .input-group input,
-#simulator-container .input-group select,
-#custom-data-modal textarea {
-    display: block;
-    width: 100%;
-    padding: 5px;
-    margin-bottom: 10px;
-    border-radius: 3px;
-    border: 1px solid #e0e0e0;
-    box-sizing: border-box;
-}
-
-#histogram-props,
-#data-options {
-    width: 50%;
-    box-sizing: border-box;
-}
-
-#data-options {
-    padding-right: 50px;
-}
-
-#data-options .input-group {
-    margin-bottom: 10px;
-}
-
-#data-options .input-group:first-of-type {
-    margin-top: 20px;
-}
-
-#data-options .input-group:last-of-type {
-    margin-bottom: 0;
-}
-
-#data-options .input-group label {
-    display: inline-block;
-}
-
-#data-options .input-group input {
-    display: inline;
-    width: auto;
-}
-
-#histogram-chart-container {
-    width: 100%;
-    padding: 30px;
-    border: 1px solid #e0e0e0;
-    margin: 30px 0;
-    overflow: hidden;
-    position: relative;
-}
-
-#histogram-chart {
-    margin-top: 50px;
-    width: 100%;
-}
-
-#histogram-chart-legend {
-    font-size: 14px;
-    text-align: center;
-    width: 100%;
-}
-
-#histogram-functional-props,
-#histogram-non-functional-props {
-    display: none;
-}
-
-#custom-data-modal-overlay {
-    background-color: rgba(0, 0, 0, .5);
-    position: fixed;
-    width: 100vw;
-    height: 100vh;
-    top: 0;
-    left: 0;
-    z-index: 999;
-    display: none;
-}
-
-#custom-data-modal {
-    width: 50%;
-    background-color: white;
-    border-radius: 5px;
-    position: relative;
-    top: 15%;
-    left: 25%;
-    padding: 50px;
-}
-
-.hide {
-    display: none !important;
-}

docs/dev/shared/mermaid-init.js

@@ -1,4 +0,0 @@
-/* This Source Code Form is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-mermaid.initialize({startOnLoad:true});

docs/dev/shared/mermaid.css

@@ -1,356 +0,0 @@
-/*
-Licensed under the MIT License (MIT).
-Copyright (c) 2014 - 2018 Knut Sveidqvist
-Full license: https://github.com/mermaid-js/mermaid/blob/develop/LICENSE
-*/
-/* Flowchart variables */
-/* Sequence Diagram variables */
-/* Gantt chart variables */
-.mermaid .mermaid .label {
-  color: #333;
-}
-.mermaid .node rect,
-.mermaid .node circle,
-.mermaid .node ellipse,
-.mermaid .node polygon {
-  fill: #ECECFF;
-  stroke: #CCCCFF;
-  stroke-width: 1px;
-}
-.mermaid .arrowheadPath {
-  fill: #333333;
-}
-.mermaid .edgePath .path {
-  stroke: #333333;
-}
-.mermaid .edgeLabel {
-  background-color: #e8e8e8;
-}
-.mermaid .cluster rect {
-  fill: #ffffde !important;
-  rx: 4 !important;
-  stroke: #aaaa33 !important;
-  stroke-width: 1px !important;
-}
-.mermaid .cluster text {
-  fill: #333;
-}
-.mermaid .actor {
-  stroke: #CCCCFF;
-  fill: #ECECFF;
-}
-.mermaid text.actor {
-  fill: black;
-  stroke: none;
-}
-.mermaid .actor-line {
-  stroke: grey;
-}
-.mermaid .messageLine0 {
-  stroke-width: 1.5;
-  stroke-dasharray: "2 2";
-  marker-end: "url(#arrowhead)";
-  stroke: #333;
-}
-.mermaid .messageLine1 {
-  stroke-width: 1.5;
-  stroke-dasharray: "2 2";
-  stroke: #333;
-}
-.mermaid #arrowhead {
-  fill: #333;
-}
-.mermaid #crosshead path {
-  fill: #333 !important;
-  stroke: #333 !important;
-}
-.mermaid .messageText {
-  fill: #333;
-  stroke: none;
-}
-.mermaid .labelBox {
-  stroke: #CCCCFF;
-  fill: #ECECFF;
-}
-.mermaid .labelText {
-  fill: black;
-  stroke: none;
-}
-.mermaid .loopText {
-  fill: black;
-  stroke: none;
-}
-.mermaid .loopLine {
-  stroke-width: 2;
-  stroke-dasharray: "2 2";
-  marker-end: "url(#arrowhead)";
-  stroke: #CCCCFF;
-}
-.mermaid .note {
-  stroke: #aaaa33;
-  fill: #fff5ad;
-}
-.mermaid .noteText {
-  fill: black;
-  stroke: none;
-  font-family: 'trebuchet ms', verdana, arial;
-  font-size: 14px;
-}
-/** Section styling */
-.mermaid .section {
-  stroke: none;
-  opacity: 0.2;
-}
-.mermaid .section0 {
-  fill: rgba(102, 102, 255, 0.49);
-}
-.mermaid .section2 {
-  fill: #fff400;
-}
-.mermaid .section1,
-.mermaid .section3 {
-  fill: white;
-  opacity: 0.2;
-}
-.mermaid .sectionTitle0 {
-  fill: #333;
-}
-.mermaid .sectionTitle1 {
-  fill: #333;
-}
-.mermaid .sectionTitle2 {
-  fill: #333;
-}
-.mermaid .sectionTitle3 {
-  fill: #333;
-}
-.mermaid .sectionTitle {
-  text-anchor: start;
-  font-size: 11px;
-  text-height: 14px;
-}
-/* Grid and axis */
-.mermaid .grid .tick {
-  stroke: lightgrey;
-  opacity: 0.3;
-  shape-rendering: crispEdges;
-}
-.mermaid .grid path {
-  stroke-width: 0;
-}
-/* Today line */
-.mermaid .today {
-  fill: none;
-  stroke: red;
-  stroke-width: 2px;
-}
-/* Task styling */
-/* Default task */
-.mermaid .task {
-  stroke-width: 2;
-}
-.mermaid .taskText {
-  text-anchor: middle;
-  font-size: 11px;
-}
-.mermaid .taskTextOutsideRight {
-  fill: black;
-  text-anchor: start;
-  font-size: 11px;
-}
-.mermaid .taskTextOutsideLeft {
-  fill: black;
-  text-anchor: end;
-  font-size: 11px;
-}
-/* Specific task settings for the sections*/
-.mermaid .taskText0,
-.mermaid .taskText1,
-.mermaid .taskText2,
-.mermaid .taskText3 {
-  fill: white;
-}
-.mermaid .task0,
-.mermaid .task1,
-.mermaid .task2,
-.mermaid .task3 {
-  fill: #8a90dd;
-  stroke: #534fbc;
-}
-.mermaid .taskTextOutside0,
-.mermaid .taskTextOutside2 {
-  fill: black;
-}
-.mermaid .taskTextOutside1,
-.mermaid .taskTextOutside3 {
-  fill: black;
-}
-/* Active task */
-.mermaid .active0,
-.mermaid .active1,
-.mermaid .active2,
-.mermaid .active3 {
-  fill: #bfc7ff;
-  stroke: #534fbc;
-}
-.mermaid .activeText0,
-.mermaid .activeText1,
-.mermaid .activeText2,
-.mermaid .activeText3 {
-  fill: black !important;
-}
-/* Completed task */
-.mermaid .done0,
-.mermaid .done1,
-.mermaid .done2,
-.mermaid .done3 {
-  stroke: grey;
-  fill: lightgrey;
-  stroke-width: 2;
-}
-.mermaid .doneText0,
-.mermaid .doneText1,
-.mermaid .doneText2,
-.mermaid .doneText3 {
-  fill: black !important;
-}
-/* Tasks on the critical line */
-.mermaid .crit0,
-.mermaid .crit1,
-.mermaid .crit2,
-.mermaid .crit3 {
-  stroke: #ff8888;
-  fill: red;
-  stroke-width: 2;
-}
-.mermaid .activeCrit0,
-.mermaid .activeCrit1,
-.mermaid .activeCrit2,
-.mermaid .activeCrit3 {
-  stroke: #ff8888;
-  fill: #bfc7ff;
-  stroke-width: 2;
-}
-.mermaid .doneCrit0,
-.mermaid .doneCrit1,
-.mermaid .doneCrit2,
-.mermaid .doneCrit3 {
-  stroke: #ff8888;
-  fill: lightgrey;
-  stroke-width: 2;
-  cursor: pointer;
-  shape-rendering: crispEdges;
-}
-.mermaid .doneCritText0,
-.mermaid .doneCritText1,
-.mermaid .doneCritText2,
-.mermaid .doneCritText3 {
-  fill: black !important;
-}
-.mermaid .activeCritText0,
-.mermaid .activeCritText1,
-.mermaid .activeCritText2,
-.mermaid .activeCritText3 {
-  fill: black !important;
-}
-.mermaid .titleText {
-  text-anchor: middle;
-  font-size: 18px;
-  fill: black;
-}
-.mermaid g.classGroup text {
-  fill: #9370DB;
-  stroke: none;
-  font-family: 'trebuchet ms', verdana, arial;
-  font-size: 10px;
-}
-.mermaid g.classGroup rect {
-  fill: #ECECFF;
-  stroke: #9370DB;
-}
-.mermaid g.classGroup line {
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid svg .classLabel .box {
-  stroke: none;
-  stroke-width: 0;
-  fill: #ECECFF;
-  opacity: 0.5;
-}
-.mermaid svg .classLabel .label {
-  fill: #9370DB;
-  font-size: 10px;
-}
-.mermaid .relation {
-  stroke: #9370DB;
-  stroke-width: 1;
-  fill: none;
-}
-.mermaid .composition {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #compositionStart {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #compositionEnd {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid .aggregation {
-  fill: #ECECFF;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #aggregationStart {
-  fill: #ECECFF;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #aggregationEnd {
-  fill: #ECECFF;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #dependencyStart {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #dependencyEnd {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #extensionStart {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #extensionEnd {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid .node text {
-  font-family: 'trebuchet ms', verdana, arial;
-  font-size: 14px;
-}
-.mermaid div.mermaidTooltip {
-  position: absolute;
-  text-align: center;
-  max-width: 200px;
-  padding: 2px;
-  font-family: 'trebuchet ms', verdana, arial;
-  font-size: 12px;
-  background: #ffffde;
-  border: 1px solid #aaaa33;
-  border-radius: 2px;
-  pointer-events: none;
-  z-index: 100;
-}

docs/dev/shared/tabs.js

@@ -1,97 +0,0 @@
-/**
- * Returns true if browser supports HTML5 localStorage.
- */
-function supportsHTML5Storage() {
-    try {
-        return 'localStorage' in window && window['localStorage'] !== null;
-    } catch (e) {
-        return false;
-    }
-}
-
-/**
- * Event handler for when a tab is clicked.
- */
-function onClickTab(event) {
-    let target = event.currentTarget;
-    let language = target.dataset.lang;
-
-    const initialTargetOffset = target.offsetTop;
-    const initialScrollPosition = window.scrollY;
-    switchAllTabs(language);
-
-    // Keep initial perceived scroll position after resizing
-    // that may happen due to activation of multiple tabs in the same page.
-    const finalTargetOffset = target.offsetTop;
-    window.scrollTo({
-        top: initialScrollPosition + (finalTargetOffset - initialTargetOffset)
-    });
-}
-
-/**
- * Switches the displayed tab for the given container.
- *
- * :param container: The div containing both the tab bar and the individual tabs
- * as direct children.
- * :param language: The language to switch to.
- */
-function switchTab(container, language) {
-    const previouslyActiveTab = container.querySelector(".tabcontents .active");
-    previouslyActiveTab && previouslyActiveTab.classList.remove("active");
-    let tab = container.querySelector(`.tabcontents [data-lang="${language}"]`);
-    tab && tab.classList.add("active");
-
-    const previouslyActiveButton = container.querySelector(".tabbar .active");
-    previouslyActiveButton && previouslyActiveButton.classList.remove("active");
-    let button = container.querySelector(`.tabbar [data-lang="${language}"]`);
-    button && button.classList.add("active");
-}
-
-/**
- * Switches all tabs on the page to the given language.
- *
- * :param language: The language to switch to.
- */
-function switchAllTabs(language) {
-    const containers = document.getElementsByClassName("tabs");
-    for (let i = 0; i < containers.length; ++i) {
-        switchTab(containers[i], language);
-    }
-
-    if (supportsHTML5Storage()) {
-        localStorage.setItem("glean-preferred-language", language);
-    }
-}
-
-/**
- * Opens all tabs on the page to the given language on page load.
- */
-function openTabs() {
-    if (!supportsHTML5Storage()) {
-        return;
-    }
-
-    let containers = document.getElementsByClassName("tabs");
-    for (let i = 0; i < containers.length; ++i) {
-        // Create tabs for every language that has content
-        let tabs = containers[i].children[0];
-        let tabcontents = containers[i].children[1];
-        for (let tabcontent of tabcontents.children) {
-            let button = document.createElement("button");
-            button.dataset.lang = tabcontent.dataset.lang;
-            button.className = "tablinks";
-            button.onclick = onClickTab;
-            button.innerText = tabcontent.dataset.lang;
-            tabs.appendChild(button);
-        }
-    }
-
-    var language = localStorage.getItem("glean-preferred-language");
-    if (language == null) {
-        language = "Kotlin";
-    }
-
-    switchAllTabs(language);
-}
-
-openTabs()

docs/user/README.md

@@ -38,25 +38,29 @@ file a bug in [Bugzilla in Data Platform & Tools :: Glean.js][gleanjs-bugs].
 > if you want to use Glean.js and is missing some key Glean feature.
 ## Sections
 
-### [Using Glean](./user/index.html)
+### [User Guides](./user/adding-glean-to-your-project.html)
+
+This section of the book contains mostly step-by-step guides and essays detailing how to
+achieve specific tasks with Glean.
+
+It contains guides on the first steps of integrating Glean into your project,
+choosing the right metric type for you, debugging products that use Glean and
+Glean's built-in error reporting mechanism.
 
-In this section we describe how to use Glean in your own libraries and applications.
-It explains the first steps of integrating Glean into your project, choosing the right metric type for you,
-debugging products that use Glean and Glean's built-in error reporting mechanism.
 If you want to start using Glean to report data, this is the section you should read.
 
-### [Metric Types](./user/metrics/index.html)
+### [API Reference](./reference/yaml/index.html)
 
-This sections lists all the metric types provided by Glean, with examples on how to define them
-and record data using them. Before diving into Glean's metric types details, don't forget to
-read the [Choosing a metric type](https://mozilla.github.io/glean/book/user/adding-new-metrics.html#choosing-a-metric-type) page.
+This section of the book contains reference pages for Glean’s user facing APIs.
 
-### [Pings](./user/pings/index.html)
+If you are looking for information a specific Glean API, this is the section you should check out.
 
-This section goes through what is a ping and how to define custom pings. A Glean client may provide
-off-the-shelf pings, such as the [`metrics`](https://mozilla.github.io/glean/book/user/pings/metrics.html)
-or [`baseline`](https://mozilla.github.io/glean/book/user/pings/baseline.html) pings. In this section,
-you will also find the descriptions and the schedules of each of these pings.
+### [Language Binding Information](./language-bindings/android/index.html)
+
+This section contains guides and essays regarding specific usage information
+and possibilities in each of Glean's language bindings.
+
+Check out this section for information on the language binding you are using.
 
 ### Appendix
 

docs/user/SUMMARY.md

@@ -1,35 +1,13 @@
 [Glean](README.md)
 
-- [Using the Glean SDK](user/index.md)
-    - [Adding Glean to your project](user/adding-glean-to-your-project.md)
-    - [The General API](user/general-api.md)
-    - [Adding new metrics](user/adding-new-metrics.md)
-    - [Metric parameters](user/metric-parameters.md)
-    - [Testing metrics](user/testing-metrics.md)
-    - [Debugging products using Glean](user/debugging/index.md)
-        - [Glean Debug Ping View](user/debugging/debug-ping-view.md)
-        - [Android](user/debugging/android.md)
-        - [iOS](user/debugging/ios.md)
-        - [Python](user/debugging/python.md)
-    - [Error reporting](user/error-reporting.md)
-    - [Using the experiments API](user/experiments-api.md)
-- [Metric types](user/metrics/index.md)
-    - [Boolean](user/metrics/boolean.md)
-    - [Labeled Booleans](user/metrics/labeled_booleans.md)
-    - [Counter](user/metrics/counter.md)
-    - [Labeled Counters](user/metrics/labeled_counters.md)
-    - [String](user/metrics/string.md)
-    - [Labeled Strings](user/metrics/labeled_strings.md)
-    - [String List](user/metrics/string_list.md)
-    - [Timespan](user/metrics/timespan.md)
-    - [Timing Distribution](user/metrics/timing_distribution.md)
-    - [Memory Distribution](user/metrics/memory_distribution.md)
-    - [UUID](user/metrics/uuid.md)
-    - [Datetime](user/metrics/datetime.md)
-    - [Event](user/metrics/event.md)
-    - [Custom Distribution](user/metrics/custom_distribution.md)
-    - [Quantity](user/metrics/quantity.md)
-    - [Rate](user/metrics/rate.md)
+# User Guides
+
+- [Adding Glean to your project](user/adding-glean-to-your-project.md)
+- [Metrics](user/metrics/adding-new-metrics.md)
+    - [Adding new metrics](user/metrics/adding-new-metrics.md)
+    - [Testing metrics](user/metrics/testing-metrics.md)
+    - [Error reporting](user/metrics/error-reporting.md)
+    - [Metrics collected by the Glean SDK](user/collected-metrics/metrics.md)
 - [Pings](user/pings/index.md)
     - [Ping schedules and timings overview](user/pings/ping-schedules-and-timings.md)
     - [Baseline Ping](user/pings/baseline.md)
@@ -38,13 +16,40 @@
     - [Events Ping](user/pings/events.md)
     - [Custom Pings](user/pings/custom.md)
     - [Testing custom pings](user/pings/testing-custom-pings.md)
-- [Android-specific information](user/android/index.md)
-    - [Android build configuration options](user/android/android-build-configuration-options.md)
-    - [Android offline builds](user/android/android-offline-builds.md)
-- [Focused Use Cases](user/focused-use-cases.md)
-    - [Instrumenting Android crashes with the Glean SDK](user/instrument-android-crashes-example.md)
-- [Metrics collected by the Glean SDK](user/collected-metrics/metrics.md)
+- [Using the experiments API](user/experiments-api.md)
+- [Debugging products using Glean](user/debugging/index.md)
+    - [Glean Debug Ping View](user/debugging/debug-ping-view.md)
+    - [Android](user/debugging/android.md)
+    - [iOS](user/debugging/ios.md)
+    - [Python](user/debugging/python.md)
+# API Reference
 
+- [YAML Format](reference/yaml/index.md)
+- [General](reference/general/index.md)
+- [Metric types](reference/metrics/index.md)
+    - [Boolean](reference/metrics/boolean.md)
+    - [Labeled Booleans](reference/metrics/labeled_booleans.md)
+    - [Counter](reference/metrics/counter.md)
+    - [Labeled Counters](reference/metrics/labeled_counters.md)
+    - [String](reference/metrics/string.md)
+    - [Labeled Strings](reference/metrics/labeled_strings.md)
+    - [String List](reference/metrics/string_list.md)
+    - [Timespan](reference/metrics/timespan.md)
+    - [Timing Distribution](reference/metrics/timing_distribution.md)
+    - [Memory Distribution](reference/metrics/memory_distribution.md)
+    - [UUID](reference/metrics/uuid.md)
+    - [Datetime](reference/metrics/datetime.md)
+    - [Event](reference/metrics/event.md)
+    - [Custom Distribution](reference/metrics/custom_distribution.md)
+    - [Quantity](reference/metrics/quantity.md)
+    - [Rate](reference/metrics/rate.md)
+
+# Language Bindings Information
+
+- [Android](language-bindings/android/index.md)
+    - [Android build configuration options](language-bindings/android/android-build-configuration-options.md)
+    - [Android offline builds](language-bindings/android/android-offline-builds.md)
+    - [Instrumenting Android crashes with the Glean SDK](language-bindings/android/instrument-android-crashes-example.md)
 # Appendix
 
 - [Glossary](appendix/glossary.md)

docs/user/collected-metrics/metrics.md

@@ -1,158 +0,0 @@
-<!-- AUTOGENERATED BY glean_parser.  DO NOT EDIT. -->
-
-# Metrics
-
-This document enumerates the metrics collected by this project using the [Glean SDK](https://mozilla.github.io/glean/book/index.html).
-This project may depend on other projects which also collect metrics.
-This means you might have to go searching through the dependency tree to get a full picture of everything collected by this project.
-
-# Pings
-
-- [all-pings](#all-pings)
-- [baseline](#baseline)
-- [deletion-request](#deletion-request)
-- [metrics](#metrics)
-
-## all-pings
-
-These metrics are sent in every ping.
-
-All Glean pings contain built-in metrics in the [`ping_info`](https://mozilla.github.io/glean/book/user/pings/index.html#the-ping_info-section) and [`client_info`](https://mozilla.github.io/glean/book/user/pings/index.html#the-client_info-section) sections.
-
-In addition to those built-in metrics, the following metrics are added to the ping:
-
-| Name | Type | Description | Data reviews | Extras | Expiration | [Data Sensitivity](https://wiki.mozilla.org/Firefox/Data_Collection) |
-| --- | --- | --- | --- | --- | --- | --- |
-| glean.error.invalid_label |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |Counts the number of times a metric was set with an invalid label. The labels are the `category.name` identifier of the metric.  |[Bug 1499761](https://bugzilla.mozilla.org/show_bug.cgi?id=1499761#c5)||never |1 |
-| glean.error.invalid_overflow |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |Counts the number of times a metric was set a value that overflowed. The labels are the `category.name` identifier of the metric.  |[Bug 1591912](https://bugzilla.mozilla.org/show_bug.cgi?id=1591912#c3)||never |1 |
-| glean.error.invalid_state |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |Counts the number of times a timing metric was used incorrectly. The labels are the `category.name` identifier of the metric.  |[Bug 1499761](https://bugzilla.mozilla.org/show_bug.cgi?id=1499761#c5)||never |1 |
-| glean.error.invalid_value |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |Counts the number of times a metric was set to an invalid value. The labels are the `category.name` identifier of the metric.  |[Bug 1499761](https://bugzilla.mozilla.org/show_bug.cgi?id=1499761#c5)||never |1 |
-
-## baseline
-
-This is a built-in ping that is assembled out of the box by the Glean SDK.
-
-See the Glean SDK documentation for the [`baseline` ping](https://mozilla.github.io/glean/book/user/pings/baseline.html).
-
-This ping is sent if empty.
-
-This ping includes the [client id](https://mozilla.github.io/glean/book/user/pings/index.html#the-client_info-section).
-
-**Data reviews for this ping:**
-
-- <https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3>
-- <https://bugzilla.mozilla.org/show_bug.cgi?id=1599877#c25>
-
-**Bugs related to this ping:**
-
-- <https://bugzilla.mozilla.org/1512938>
-- <https://bugzilla.mozilla.org/1599877>
-
-**Reasons this ping may be sent:**
-
-- `active`: The ping was submitted when the application became active again, which
-      includes when the application starts. In earlier versions, this was called
-      `foreground`.
-
-      *Note*: this ping will not contain the `glean.baseline.duration` metric.
-
-- `dirty_startup`: The ping was submitted at startup, because the application process was
-      killed before the Glean SDK had the chance to generate this ping, before
-      becoming inactive, in the last session.
-
-      *Note*: this ping will not contain the `glean.baseline.duration` metric.
-
-- `inactive`: The ping was submitted when becoming inactive. In earlier versions, this
-      was called `background`.
-
-
-All Glean pings contain built-in metrics in the [`ping_info`](https://mozilla.github.io/glean/book/user/pings/index.html#the-ping_info-section) and [`client_info`](https://mozilla.github.io/glean/book/user/pings/index.html#the-client_info-section) sections.
-
-In addition to those built-in metrics, the following metrics are added to the ping:
-
-| Name | Type | Description | Data reviews | Extras | Expiration | [Data Sensitivity](https://wiki.mozilla.org/Firefox/Data_Collection) |
-| --- | --- | --- | --- | --- | --- | --- |
-| glean.baseline.duration |[timespan](https://mozilla.github.io/glean/book/user/metrics/timespan.html) |The duration of the last foreground session.  |[Bug 1512938](https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3)||never |1, 2 |
-| glean.validation.first_run_hour |[datetime](https://mozilla.github.io/glean/book/user/metrics/datetime.html) |The hour of the first run of the application.  |[Bug 1680783](https://bugzilla.mozilla.org/show_bug.cgi?id=1680783#c5)||never |1 |
-| glean.validation.pings_submitted |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |A count of the pings submitted, by ping type.  This metric appears in both the metrics and baseline pings.  - On the metrics ping, the counts include the number of pings sent since   the last metrics ping (including the last metrics ping) - On the baseline ping, the counts include the number of pings send since   the last baseline ping (including the last baseline ping)  |[Bug 1586764](https://bugzilla.mozilla.org/show_bug.cgi?id=1586764#c3)||never |1 |
-
-## deletion-request
-
-This is a built-in ping that is assembled out of the box by the Glean SDK.
-
-See the Glean SDK documentation for the [`deletion-request` ping](https://mozilla.github.io/glean/book/user/pings/deletion-request.html).
-
-This ping is sent if empty.
-
-This ping includes the [client id](https://mozilla.github.io/glean/book/user/pings/index.html#the-client_info-section).
-
-**Data reviews for this ping:**
-
-- <https://bugzilla.mozilla.org/show_bug.cgi?id=1587095#c6>
-
-**Bugs related to this ping:**
-
-- <https://bugzilla.mozilla.org/1587095>
-
-All Glean pings contain built-in metrics in the [`ping_info`](https://mozilla.github.io/glean/book/user/pings/index.html#the-ping_info-section) and [`client_info`](https://mozilla.github.io/glean/book/user/pings/index.html#the-client_info-section) sections.
-
-This ping contains no metrics.
-
-## metrics
-
-This is a built-in ping that is assembled out of the box by the Glean SDK.
-
-See the Glean SDK documentation for the [`metrics` ping](https://mozilla.github.io/glean/book/user/pings/metrics.html).
-
-This ping includes the [client id](https://mozilla.github.io/glean/book/user/pings/index.html#the-client_info-section).
-
-**Data reviews for this ping:**
-
-- <https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3>
-- <https://bugzilla.mozilla.org/show_bug.cgi?id=1557048#c13>
-
-**Bugs related to this ping:**
-
-- <https://bugzilla.mozilla.org/1512938>
-
-**Reasons this ping may be sent:**
-
-- `overdue`: The last ping wasn't submitted on the current calendar day, but it's after
-      4am, so this ping submitted immediately
-
-- `reschedule`: A ping was just submitted. This ping was rescheduled for the next calendar
-      day at 4am.
-
-- `today`: The last ping wasn't submitted on the current calendar day, but it is
-      still before 4am, so schedule to send this ping on the current calendar
-      day at 4am.
-
-- `tomorrow`: The last ping was already submitted on the current calendar day, so
-      schedule this ping for the next calendar day at 4am.
-
-- `upgrade`: This ping was submitted at startup because the application was just
-      upgraded.
-
-
-All Glean pings contain built-in metrics in the [`ping_info`](https://mozilla.github.io/glean/book/user/pings/index.html#the-ping_info-section) and [`client_info`](https://mozilla.github.io/glean/book/user/pings/index.html#the-client_info-section) sections.
-
-In addition to those built-in metrics, the following metrics are added to the ping:
-
-| Name | Type | Description | Data reviews | Extras | Expiration | [Data Sensitivity](https://wiki.mozilla.org/Firefox/Data_Collection) |
-| --- | --- | --- | --- | --- | --- | --- |
-| glean.database.size |[memory_distribution](https://mozilla.github.io/glean/book/user/metrics/memory_distribution.html) |The size of the database file at startup.  |[Bug 1656589](https://bugzilla.mozilla.org/show_bug.cgi?id=1656589#c7)||never |1 |
-| glean.error.io |[counter](https://mozilla.github.io/glean/book/user/metrics/counter.html) |The number of times we encountered an IO error when writing a pending ping to disk.  |[Bug 1686233](https://bugzilla.mozilla.org/show_bug.cgi?id=1686233#c2)||never |1 |
-| glean.error.preinit_tasks_overflow |[counter](https://mozilla.github.io/glean/book/user/metrics/counter.html) |The number of tasks queued in the pre-initialization buffer. Only sent if the buffer overflows.  |[Bug 1609482](https://bugzilla.mozilla.org/show_bug.cgi?id=1609482#c3)||never |1 |
-| glean.upload.deleted_pings_after_quota_hit |[counter](https://mozilla.github.io/glean/book/user/metrics/counter.html) |The number of pings deleted after the quota for the size of the pending pings directory or number of files is hit. Since quota is only calculated for the pending pings directory, and deletion request ping live in a different directory, deletion request pings are never deleted.  |[Bug 1601550](https://bugzilla.mozilla.org/show_bug.cgi?id=1601550#c3)||never |1 |
-| glean.upload.discarded_exceeding_pings_size |[memory_distribution](https://mozilla.github.io/glean/book/user/metrics/memory_distribution.html) |The size of pings that exceeded the maximum ping size allowed for upload.  |[Bug 1597761](https://bugzilla.mozilla.org/show_bug.cgi?id=1597761#c10)||never |1 |
-| glean.upload.pending_pings |[counter](https://mozilla.github.io/glean/book/user/metrics/counter.html) |The total number of pending pings at startup. This does not include deletion-request pings.  |[Bug 1665041](https://bugzilla.mozilla.org/show_bug.cgi?id=1665041#c23)||never |1 |
-| glean.upload.pending_pings_directory_size |[memory_distribution](https://mozilla.github.io/glean/book/user/metrics/memory_distribution.html) |The size of the pending pings directory upon initialization of Glean. This does not include the size of the deletion request pings directory.  |[Bug 1601550](https://bugzilla.mozilla.org/show_bug.cgi?id=1601550#c3)||never |1 |
-| glean.upload.ping_upload_failure |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |Counts the number of ping upload failures, by type of failure. This includes failures for all ping types, though the counts appear in the next successfully sent `metrics` ping.  |[Bug 1589124](https://bugzilla.mozilla.org/show_bug.cgi?id=1589124#c1)|<ul><li>status_code_4xx</li><li>status_code_5xx</li><li>status_code_unknown</li><li>unrecoverable</li><li>recoverable</li></ul>|never |1 |
-| glean.validation.first_run_hour |[datetime](https://mozilla.github.io/glean/book/user/metrics/datetime.html) |The hour of the first run of the application.  |[Bug 1680783](https://bugzilla.mozilla.org/show_bug.cgi?id=1680783#c5)||never |1 |
-| glean.validation.foreground_count |[counter](https://mozilla.github.io/glean/book/user/metrics/counter.html) |On mobile, the number of times the application went to foreground.  |[Bug 1683707](https://bugzilla.mozilla.org/show_bug.cgi?id=1683707#c2)||never |1 |
-| glean.validation.pings_submitted |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |A count of the pings submitted, by ping type.  This metric appears in both the metrics and baseline pings.  - On the metrics ping, the counts include the number of pings sent since   the last metrics ping (including the last metrics ping) - On the baseline ping, the counts include the number of pings send since   the last baseline ping (including the last baseline ping)  |[Bug 1586764](https://bugzilla.mozilla.org/show_bug.cgi?id=1586764#c3)||never |1 |
-
-Data categories are [defined here](https://wiki.mozilla.org/Firefox/Data_Collection).
-
-<!-- AUTOGENERATED BY glean_parser.  DO NOT EDIT. -->
-

docs/user/language-bindings/android/instrument-android-crashes-example.md

@@ -17,19 +17,19 @@ helpful in following this guide.
 
 ## Setup Build Configuration
 
-Please follow the instruction in the ["Adding Glean to your project"](adding-glean-to-your-project.md) chapter in order to set up
+Please follow the instruction in the ["Adding Glean to your project"](../../user/adding-glean-to-your-project.md) chapter in order to set up
 Glean in an Android project.
 
 ### Add A Custom Metric
 
 Since crashes will be instrumented with some custom metrics, the next step will be to add a `metrics.yaml` file to define the
 metrics used to record the crash information and a `pings.yaml` file to define a custom ping which will give some control over
-the scheduling of the uploading.  See ["Adding new metrics"](adding-new-metrics.md) for more information about adding metrics.
+the scheduling of the uploading.  See ["Adding new metrics"](../../user/adding-new-metrics.md) for more information about adding metrics.
 
-What metric type should be used to represent the crash data?  While this could be implemented several ways, an [event](metrics/event.md) is an
+What metric type should be used to represent the crash data?  While this could be implemented several ways, an [event](../../reference/metrics/event.md) is an
 excellent choice, simply because events capture information in a nice concise way and they have a built-in way of passing
 additional information using the `extras` field.  If it is necessary to pass along the cause of the exception or a few lines of
-description, events let us do that easily (with [some limitations](metrics/event.md#limits)).
+description, events let us do that easily (with [some limitations](../../reference/metrics/event.md#limits)).
 
 Now that a metric type has been chosen to represent the metric, the next step is creating the `metrics.yaml`.  Inside of the
 root application folder of the Android Studio project create a new file named `metrics.yaml`.  After adding the schema
@@ -72,7 +72,7 @@ and `message`.  This allows for sending additional information along with the ev
 ### Add A Custom Ping
 
 Define the custom ping that will help control the upload scheduling by creating a `pings.yaml` file in the same directory as
-the `metrics.yaml` file.  For more information about adding custom pings, see the section on [custom pings](pings/custom.md).  
+the `metrics.yaml` file.  For more information about adding custom pings, see the section on [custom pings](../../user/pings/custom.md).  
 The name of the ping will be `crash`, so the `pings.yaml` file should look like this:
 
 ```YAML

docs/user/reference/general/index.md

@@ -3,8 +3,8 @@
 The Glean SDK has a minimal API available on its top-level `Glean` object.
 This API allows one to enable and disable upload, register [custom pings][custom-pings] and set [experiment data][experiments-api].
 
-[custom-pings]: pings/custom.md
-[experiments-api]: experiments-api.md
+[custom-pings]: ../../user/pings/custom.md
+[experiments-api]: ../../user/experiments-api.md
 
 > **Important:** The Glean SDK should only be initialized from the main application, not individual libraries.
 
@@ -34,7 +34,7 @@ The following steps are required for applications using the Glean SDK, but not l
 >
 > This does not apply to special builds where telemetry is disabled at build time. In that case, it is acceptable to not call `initialize` at all.
 
-{{#include ../../shared/tab_header.md}}
+{{#include ../../../shared/tab_header.md}}
 
 <div data-lang="Kotlin" class="tab">
 
@@ -69,7 +69,7 @@ class SampleApplication : Application() {
 }
 ```
 
-Once initialized, if `uploadEnabled` is true, the Glean SDK will automatically start collecting [baseline metrics](pings/metrics.md) and sending its [pings](pings/index.md), according to their respective schedules.
+Once initialized, if `uploadEnabled` is true, the Glean SDK will automatically start collecting [baseline metrics](../../user/pings/metrics.md) and sending its [pings](../../user/pings/index.md), according to their respective schedules.
 If `uploadEnabled` is false, any persisted metrics, events and pings (other than `first_run_date` and `first_run_hour`) are cleared, and subsequent calls to record metrics will be no-ops.
 
 The Glean SDK should be initialized as soon as possible, and importantly, before any other libraries in the application start using Glean.
@@ -140,7 +140,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 }
 ```
 
-Once initialized, if `uploadEnabled` is true, the Glean SDK will automatically start collecting [baseline metrics](pings/metrics.md) and sending its [pings](pings/index.md), according to their respective schedules.
+Once initialized, if `uploadEnabled` is true, the Glean SDK will automatically start collecting [baseline metrics](../../user/pings/metrics.md) and sending its [pings](../../user/pings/index.md), according to their respective schedules.
 If `uploadEnabled` is false, any persisted metrics, events and pings (other than `first_run_date` and `first_run_hour`) are cleared, and subsequent calls to record metrics will be no-ops.
 
 The Glean SDK should be initialized as soon as possible, and importantly, before any other libraries in the application start using Glean.
@@ -173,13 +173,13 @@ Glean.initialize(
 )
 ```
 
-Once initialized, if `upload_enabled` is true, the Glean SDK will automatically start collecting [baseline metrics](pings/metrics.md).
+Once initialized, if `upload_enabled` is true, the Glean SDK will automatically start collecting [baseline metrics](../../user/pings/metrics.md).
 If `upload_enabled` is false, any persisted metrics, events and pings (other than `first_run_date` and `first_run_hour`) are cleared, and subsequent calls to record metrics will be no-ops.
 
 Additional configuration is available on the `glean.Configuration` object, which can be passed into `Glean.initialize()`.
 
 Unlike Android and Swift, the Python bindings do not automatically send any pings.
-See the [custom pings documentation](pings/custom.md) about adding custom pings and sending them.
+See the [custom pings documentation](../../user/pings/custom.md) about adding custom pings and sending them.
 
 </div>
 
@@ -205,7 +205,7 @@ GleanInstance.Initialize(
 
 </div>
 
-{{#include ../../shared/tab_footer.md}}
+{{#include ../../../shared/tab_footer.md}}
 
 ## Behavior when uninitialized
 
@@ -219,7 +219,7 @@ Built-in pings are only available after initialization.
 
 ## Enabling and disabling metrics
 
-{{#include ../../shared/tab_header.md}}
+{{#include ../../../shared/tab_header.md}}
 
 <div data-lang="Kotlin" class="tab">
 
@@ -261,9 +261,9 @@ Set the initial state using `uploadEnabled` on `GleanInstance.initialize()`.
 
 </div>
 
-{{#include ../../shared/tab_footer.md}}
+{{#include ../../../shared/tab_footer.md}}
 
 The application should provide some form of user interface to call this method.
 
-When going from enabled to disabled, all pending events, metrics and pings are cleared, except for [`first_run_date` and `first_run_hour`](pings/index.html#the-client_info-section).
+When going from enabled to disabled, all pending events, metrics and pings are cleared, except for [`first_run_date` and `first_run_hour`](../../user/pings/index.html#the-client_info-section).
 When re-enabling, core Glean metrics will be recomputed at that time.

docs/user/reference/metrics/index.md

@@ -0,0 +1,78 @@
+# Metrics
+
+> **Not sure which metric type to use?** These docs contain a [series of questions](../../user/metrics/adding-new-metrics.html#choosing-a-metric-type) that can help. Reference information about each metric type is linked below.
+
+The parameters available that apply to any metric type are in the [metric parameters page](../yaml/index.html).
+
+There are different metrics to choose from, depending on what you want to achieve:
+
+* [Boolean](boolean.md): Records a single truth value, for example "is a11y enabled?"
+
+* [Labeled boolean](labeled_booleans.md): Records truth values for a set of labels, for example "which a11y features are enabled?"
+
+* [Counter](counter.md): Used to count how often something happens, for example, how often a certain button was pressed.
+
+* [Labeled counter](labeled_counters.md): Used to count how often something happens, for example which kind of crash occurred (`"uncaught_exception"` or `"native_code_crash"`).
+
+* [String](string.md): Records a single Unicode string value, for example the name of the OS.
+
+* [Labeled strings](labeled_strings.md): Records multiple Unicode string values, for example to record which kind of error occurred in different stages of a login process.
+
+* [String List](string_list.md): Records a list of Unicode string values, for example the list of enabled search engines.
+
+* [Timespan](timespan.md): Used to measure how much time is spent in a single task.
+
+* [Timing Distribution](timing_distribution.md): Used to record the distribution of multiple time measurements.
+
+* [Memory Distribution](memory_distribution.md): Used to record the distribution of memory sizes.
+
+* [UUID](uuid.md): Used to record universally unique identifiers (UUIDs), such as a client ID.
+
+* [Datetime](datetime.md): Used to record an absolute date and time, such as the time the user first ran the application.
+
+* [Events](event.md): Records events e.g. individual occurrences of user actions, say every time a view was open and from where.
+
+* [Quantity](quantity.md): Used to record a single non-negative integer value. For example, the width of the display in pixels.
+
+* [Rate](rate.md): Used to record the rate something happens relative to some other thing.
+  For example, the number of HTTP connections that experienced an error relative to the number of total HTTP connections made.
+
+* [Custom Distribution](custom_distribution.md): Used to record the distribution of a value that needs fine-grained control of how the histogram buckets are computed.  **Custom distributions are only available for values that come from Gecko.**
+
+## Labeled metrics
+
+There are two types of metrics listed above - *labeled* and *unlabeled* metrics. If a metric is *labeled*, it means that for a single metric entry you define in `metrics.yaml`, you can record into multiple metrics under the same name, each of the same type and identified by a different string label.
+
+This is useful when you need to break down metrics by a label known at build time or run time. For example:
+
+- When you want to count a different set of sub-views that users interact with, you could use `viewCount["view1"].add()` and `viewCount["view2"].add()`.
+
+- When you want to count errors that might occur for a feature, you could use `errorCount[errorName].add()`.
+
+Labeled metrics come in two forms:
+
+- **Static labels**: The labels are specified at build time in the `metrics.yaml` file, in the `labels` parameter.
+  If a label that isn't part of this set is used at run time, it is converted to the special label `__other__`.
+  The number of static labels is limited to 100 per metric.
+
+- **Dynamic labels**: The labels aren't known at build time, so are set at run time.
+  Only the first 16 labels seen by the Glean SDK will be tracked. After that, any additional labels are converted to the special label `__other__`.
+
+> **Note**: Be careful with using arbitrary strings as labels and make sure they can't accidentally contain identifying data (like directory paths or user input).
+
+### Label format
+
+To ensure maximum support in database columns, labels must be made up of dot-separated identifiers with lowercase ASCII alphanumerics, containing underscores and dashes.
+
+Specifically, they must conform to this regular expression:
+
+```
+^[a-z_][a-z0-9_-]{0,29}(\\.[a-z_][a-z0-9_-]{0,29})*$
+```
+
+## Adding or changing metric types
+Glean has a [well-defined process](https://wiki.mozilla.org/Glean/Adding_or_changing_Glean_metric_types) for requesting changes to existing metric types or suggesting the implementation of new metric types:
+
+1.  Glean consumers need to file a bug in the [Data platforms & tools::Glean Metric Types](https://bugzilla.mozilla.org/enter_bug.cgi?product=Data%20Platform%20and%20Tools&component=Glean%20Metric%20Types) component, filling in the provided form;
+2.  The triage owner of the Bugzilla component prioritizes this within 6 business days and kicks off the [decision making process](https://wiki.mozilla.org/Glean/Adding_or_changing_Glean_metric_types#The_decision_making_process).
+3.  Once the decision process is completed, the bug is closed with a comment outlining the decision that was made.

docs/user/reference/yaml/index.md

@@ -2,7 +2,7 @@
 
 ## Required metric parameters
 
-- `type`: **Required.**  Specifies the type of a metric, like "counter" or "event". This defines which operations are valid for the metric, how it is stored and how data analysis tooling displays it. See the list of [supported metric types](metrics/index.md).
+- `type`: **Required.**  Specifies the type of a metric, like "counter" or "event". This defines which operations are valid for the metric, how it is stored and how data analysis tooling displays it. See the list of [supported metric types](../metrics/index.md).
 
 > **Important**: Once a metric is released in a product, its `type` should not be changed. If any data was collected locally with the older `type`, and hasn't yet been sent in a ping, recording data with the new `type` may cause any old persisted data to be lost for that metric. See [this comment](https://bugzilla.mozilla.org/show_bug.cgi?id=1621757#c1) for an extended explanation of the different scenarios.
 
@@ -26,14 +26,14 @@
     Generally, when a metric is no longer needed, it should simply be removed. This does not affect the availability of data already collected by the pipeline.
   - `never`: This metric never expires.
   - `expired`: This metric is manually expired.
-  
+
 ## Optional metric parameters
 
 - `lifetime`: Defines the lifetime of the metric. Different lifetimes affect when the metrics value is reset.
 
-{{#include lifetimes-parameters.md}}
-    
-- `send_in_pings`: Defines which pings the metric should be sent on. If not specified, the metric is sent on the "default ping", which is the `events` ping for events and the `metrics` ping for everything else. Most metrics don't need to specify this unless they are sent on [custom pings](pings/custom.md).
+{{#include ../../_includes/lifetimes-parameters.md}}
+
+- `send_in_pings`: Defines which pings the metric should be sent on. If not specified, the metric is sent on the "default ping", which is the `events` ping for events and the `metrics` ping for everything else. Most metrics don't need to specify this unless they are sent on [custom pings](../../user/pings/custom.md).
 
 - `disabled`: (default: `false`) Data collection for this metric is disabled.
   This is useful when you want to temporarily disable the collection for a specific metric without removing references to it in your source code.

docs/user/shared/glean.css

@@ -1,169 +0,0 @@
-/* Style the tab */
-.tabbar {
-    overflow: hidden;
-    border: 1px solid #ccc;
-    background-color: #f1f1f1;
-}
-
-/* Style the buttons that are used to open the tab content */
-.tabbar button {
-    background-color: inherit;
-    float: left;
-    border: none;
-    outline: none;
-    cursor: pointer;
-    padding: 14px 16px;
-    transition: 0.3s;
-}
-
-/* Change background color of buttons on hover */
-.tabbar button:hover {
-    background-color: #ddd;
-}
-
-/* Create an active/current tablink class */
-.tabbar button.active {
-    background-color: #ccc;
-}
-
-/* The container that holds all of the tab contents */
-.tabcontents {
-    display: flex;
-}
-
-/* The container for each individual language */
-.tab {
-    display: none;
-    width: 100%;
-    border: 1px solid #ccc;
-    border-top: none;
-    padding: 6px 12px;
-}
-
-.tab.active {
-    display: block;
-}
-
-/* The footer with the "Open on GitHub" link */
-footer#open-on-gh {
-  font-size: 0.8em;
-  text-align: center;
-  border-top: 1px solid black;
-  padding: 5px 0;
-}
-
-/* Distribution simulator styles */
-
-#simulator-container {
-    display: flex;
-    flex-wrap: wrap;
-    overflow: hidden;
-}
-
-#simulator-container h3 {
-    margin-top: 20px;
-}
-
-#simulator-container .input-group {
-    width: 100%;
-}
-
-#simulator-container .input-group label {
-    display: block;
-    font-weight: bold;
-    font-size: 14px;
-    margin-bottom: 7px;
-}
-
-#simulator-container .input-group input,
-#simulator-container .input-group select,
-#custom-data-modal textarea {
-    display: block;
-    width: 100%;
-    padding: 5px;
-    margin-bottom: 10px;
-    border-radius: 3px;
-    border: 1px solid #e0e0e0;
-    box-sizing: border-box;
-}
-
-#histogram-props,
-#data-options {
-    width: 50%;
-    box-sizing: border-box;
-}
-
-#data-options {
-    padding-right: 50px;
-}
-
-#data-options .input-group {
-    margin-bottom: 10px;
-}
-
-#data-options .input-group:first-of-type {
-    margin-top: 20px;
-}
-
-#data-options .input-group:last-of-type {
-    margin-bottom: 0;
-}
-
-#data-options .input-group label {
-    display: inline-block;
-}
-
-#data-options .input-group input {
-    display: inline;
-    width: auto;
-}
-
-#histogram-chart-container {
-    width: 100%;
-    padding: 30px;
-    border: 1px solid #e0e0e0;
-    margin: 30px 0;
-    overflow: hidden;
-    position: relative;
-}
-
-#histogram-chart {
-    margin-top: 50px;
-    width: 100%;
-}
-
-#histogram-chart-legend {
-    font-size: 14px;
-    text-align: center;
-    width: 100%;
-}
-
-#histogram-functional-props,
-#histogram-non-functional-props {
-    display: none;
-}
-
-#custom-data-modal-overlay {
-    background-color: rgba(0, 0, 0, .5);
-    position: fixed;
-    width: 100vw;
-    height: 100vh;
-    top: 0;
-    left: 0;
-    z-index: 999;
-    display: none;
-}
-
-#custom-data-modal {
-    width: 50%;
-    background-color: white;
-    border-radius: 5px;
-    position: relative;
-    top: 15%;
-    left: 25%;
-    padding: 50px;
-}
-
-.hide {
-    display: none !important;
-}

docs/user/shared/mermaid-init.js

@@ -1,4 +0,0 @@
-/* This Source Code Form is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-mermaid.initialize({startOnLoad:true});

docs/user/shared/mermaid.css

@@ -1,356 +0,0 @@
-/*
-Licensed under the MIT License (MIT).
-Copyright (c) 2014 - 2018 Knut Sveidqvist
-Full license: https://github.com/mermaid-js/mermaid/blob/develop/LICENSE
-*/
-/* Flowchart variables */
-/* Sequence Diagram variables */
-/* Gantt chart variables */
-.mermaid .mermaid .label {
-  color: #333;
-}
-.mermaid .node rect,
-.mermaid .node circle,
-.mermaid .node ellipse,
-.mermaid .node polygon {
-  fill: #ECECFF;
-  stroke: #CCCCFF;
-  stroke-width: 1px;
-}
-.mermaid .arrowheadPath {
-  fill: #333333;
-}
-.mermaid .edgePath .path {
-  stroke: #333333;
-}
-.mermaid .edgeLabel {
-  background-color: #e8e8e8;
-}
-.mermaid .cluster rect {
-  fill: #ffffde !important;
-  rx: 4 !important;
-  stroke: #aaaa33 !important;
-  stroke-width: 1px !important;
-}
-.mermaid .cluster text {
-  fill: #333;
-}
-.mermaid .actor {
-  stroke: #CCCCFF;
-  fill: #ECECFF;
-}
-.mermaid text.actor {
-  fill: black;
-  stroke: none;
-}
-.mermaid .actor-line {
-  stroke: grey;
-}
-.mermaid .messageLine0 {
-  stroke-width: 1.5;
-  stroke-dasharray: "2 2";
-  marker-end: "url(#arrowhead)";
-  stroke: #333;
-}
-.mermaid .messageLine1 {
-  stroke-width: 1.5;
-  stroke-dasharray: "2 2";
-  stroke: #333;
-}
-.mermaid #arrowhead {
-  fill: #333;
-}
-.mermaid #crosshead path {
-  fill: #333 !important;
-  stroke: #333 !important;
-}
-.mermaid .messageText {
-  fill: #333;
-  stroke: none;
-}
-.mermaid .labelBox {
-  stroke: #CCCCFF;
-  fill: #ECECFF;
-}
-.mermaid .labelText {
-  fill: black;
-  stroke: none;
-}
-.mermaid .loopText {
-  fill: black;
-  stroke: none;
-}
-.mermaid .loopLine {
-  stroke-width: 2;
-  stroke-dasharray: "2 2";
-  marker-end: "url(#arrowhead)";
-  stroke: #CCCCFF;
-}
-.mermaid .note {
-  stroke: #aaaa33;
-  fill: #fff5ad;
-}
-.mermaid .noteText {
-  fill: black;
-  stroke: none;
-  font-family: 'trebuchet ms', verdana, arial;
-  font-size: 14px;
-}
-/** Section styling */
-.mermaid .section {
-  stroke: none;
-  opacity: 0.2;
-}
-.mermaid .section0 {
-  fill: rgba(102, 102, 255, 0.49);
-}
-.mermaid .section2 {
-  fill: #fff400;
-}
-.mermaid .section1,
-.mermaid .section3 {
-  fill: white;
-  opacity: 0.2;
-}
-.mermaid .sectionTitle0 {
-  fill: #333;
-}
-.mermaid .sectionTitle1 {
-  fill: #333;
-}
-.mermaid .sectionTitle2 {
-  fill: #333;
-}
-.mermaid .sectionTitle3 {
-  fill: #333;
-}
-.mermaid .sectionTitle {
-  text-anchor: start;
-  font-size: 11px;
-  text-height: 14px;
-}
-/* Grid and axis */
-.mermaid .grid .tick {
-  stroke: lightgrey;
-  opacity: 0.3;
-  shape-rendering: crispEdges;
-}
-.mermaid .grid path {
-  stroke-width: 0;
-}
-/* Today line */
-.mermaid .today {
-  fill: none;
-  stroke: red;
-  stroke-width: 2px;
-}
-/* Task styling */
-/* Default task */
-.mermaid .task {
-  stroke-width: 2;
-}
-.mermaid .taskText {
-  text-anchor: middle;
-  font-size: 11px;
-}
-.mermaid .taskTextOutsideRight {
-  fill: black;
-  text-anchor: start;
-  font-size: 11px;
-}
-.mermaid .taskTextOutsideLeft {
-  fill: black;
-  text-anchor: end;
-  font-size: 11px;
-}
-/* Specific task settings for the sections*/
-.mermaid .taskText0,
-.mermaid .taskText1,
-.mermaid .taskText2,
-.mermaid .taskText3 {
-  fill: white;
-}
-.mermaid .task0,
-.mermaid .task1,
-.mermaid .task2,
-.mermaid .task3 {
-  fill: #8a90dd;
-  stroke: #534fbc;
-}
-.mermaid .taskTextOutside0,
-.mermaid .taskTextOutside2 {
-  fill: black;
-}
-.mermaid .taskTextOutside1,
-.mermaid .taskTextOutside3 {
-  fill: black;
-}
-/* Active task */
-.mermaid .active0,
-.mermaid .active1,
-.mermaid .active2,
-.mermaid .active3 {
-  fill: #bfc7ff;
-  stroke: #534fbc;
-}
-.mermaid .activeText0,
-.mermaid .activeText1,
-.mermaid .activeText2,
-.mermaid .activeText3 {
-  fill: black !important;
-}
-/* Completed task */
-.mermaid .done0,
-.mermaid .done1,
-.mermaid .done2,
-.mermaid .done3 {
-  stroke: grey;
-  fill: lightgrey;
-  stroke-width: 2;
-}
-.mermaid .doneText0,
-.mermaid .doneText1,
-.mermaid .doneText2,
-.mermaid .doneText3 {
-  fill: black !important;
-}
-/* Tasks on the critical line */
-.mermaid .crit0,
-.mermaid .crit1,
-.mermaid .crit2,
-.mermaid .crit3 {
-  stroke: #ff8888;
-  fill: red;
-  stroke-width: 2;
-}
-.mermaid .activeCrit0,
-.mermaid .activeCrit1,
-.mermaid .activeCrit2,
-.mermaid .activeCrit3 {
-  stroke: #ff8888;
-  fill: #bfc7ff;
-  stroke-width: 2;
-}
-.mermaid .doneCrit0,
-.mermaid .doneCrit1,
-.mermaid .doneCrit2,
-.mermaid .doneCrit3 {
-  stroke: #ff8888;
-  fill: lightgrey;
-  stroke-width: 2;
-  cursor: pointer;
-  shape-rendering: crispEdges;
-}
-.mermaid .doneCritText0,
-.mermaid .doneCritText1,
-.mermaid .doneCritText2,
-.mermaid .doneCritText3 {
-  fill: black !important;
-}
-.mermaid .activeCritText0,
-.mermaid .activeCritText1,
-.mermaid .activeCritText2,
-.mermaid .activeCritText3 {
-  fill: black !important;
-}
-.mermaid .titleText {
-  text-anchor: middle;
-  font-size: 18px;
-  fill: black;
-}
-.mermaid g.classGroup text {
-  fill: #9370DB;
-  stroke: none;
-  font-family: 'trebuchet ms', verdana, arial;
-  font-size: 10px;
-}
-.mermaid g.classGroup rect {
-  fill: #ECECFF;
-  stroke: #9370DB;
-}
-.mermaid g.classGroup line {
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid svg .classLabel .box {
-  stroke: none;
-  stroke-width: 0;
-  fill: #ECECFF;
-  opacity: 0.5;
-}
-.mermaid svg .classLabel .label {
-  fill: #9370DB;
-  font-size: 10px;
-}
-.mermaid .relation {
-  stroke: #9370DB;
-  stroke-width: 1;
-  fill: none;
-}
-.mermaid .composition {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #compositionStart {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #compositionEnd {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid .aggregation {
-  fill: #ECECFF;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #aggregationStart {
-  fill: #ECECFF;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #aggregationEnd {
-  fill: #ECECFF;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #dependencyStart {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #dependencyEnd {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #extensionStart {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid #extensionEnd {
-  fill: #9370DB;
-  stroke: #9370DB;
-  stroke-width: 1;
-}
-.mermaid .node text {
-  font-family: 'trebuchet ms', verdana, arial;
-  font-size: 14px;
-}
-.mermaid div.mermaidTooltip {
-  position: absolute;
-  text-align: center;
-  max-width: 200px;
-  padding: 2px;
-  font-family: 'trebuchet ms', verdana, arial;
-  font-size: 12px;
-  background: #ffffde;
-  border: 1px solid #aaaa33;
-  border-radius: 2px;
-  pointer-events: none;
-  z-index: 100;
-}

docs/user/shared/tabs.js

@@ -1,97 +0,0 @@
-/**
- * Returns true if browser supports HTML5 localStorage.
- */
-function supportsHTML5Storage() {
-    try {
-        return 'localStorage' in window && window['localStorage'] !== null;
-    } catch (e) {
-        return false;
-    }
-}
-
-/**
- * Event handler for when a tab is clicked.
- */
-function onClickTab(event) {
-    let target = event.currentTarget;
-    let language = target.dataset.lang;
-
-    const initialTargetOffset = target.offsetTop;
-    const initialScrollPosition = window.scrollY;
-    switchAllTabs(language);
-
-    // Keep initial perceived scroll position after resizing
-    // that may happen due to activation of multiple tabs in the same page.
-    const finalTargetOffset = target.offsetTop;
-    window.scrollTo({
-        top: initialScrollPosition + (finalTargetOffset - initialTargetOffset)
-    });
-}
-
-/**
- * Switches the displayed tab for the given container.
- *
- * :param container: The div containing both the tab bar and the individual tabs
- * as direct children.
- * :param language: The language to switch to.
- */
-function switchTab(container, language) {
-    const previouslyActiveTab = container.querySelector(".tabcontents .active");
-    previouslyActiveTab && previouslyActiveTab.classList.remove("active");
-    let tab = container.querySelector(`.tabcontents [data-lang="${language}"]`);
-    tab && tab.classList.add("active");
-
-    const previouslyActiveButton = container.querySelector(".tabbar .active");
-    previouslyActiveButton && previouslyActiveButton.classList.remove("active");
-    let button = container.querySelector(`.tabbar [data-lang="${language}"]`);
-    button && button.classList.add("active");
-}
-
-/**
- * Switches all tabs on the page to the given language.
- *
- * :param language: The language to switch to.
- */
-function switchAllTabs(language) {
-    const containers = document.getElementsByClassName("tabs");
-    for (let i = 0; i < containers.length; ++i) {
-        switchTab(containers[i], language);
-    }
-
-    if (supportsHTML5Storage()) {
-        localStorage.setItem("glean-preferred-language", language);
-    }
-}
-
-/**
- * Opens all tabs on the page to the given language on page load.
- */
-function openTabs() {
-    if (!supportsHTML5Storage()) {
-        return;
-    }
-
-    let containers = document.getElementsByClassName("tabs");
-    for (let i = 0; i < containers.length; ++i) {
-        // Create tabs for every language that has content
-        let tabs = containers[i].children[0];
-        let tabcontents = containers[i].children[1];
-        for (let tabcontent of tabcontents.children) {
-            let button = document.createElement("button");
-            button.dataset.lang = tabcontent.dataset.lang;
-            button.className = "tablinks";
-            button.onclick = onClickTab;
-            button.innerText = tabcontent.dataset.lang;
-            tabs.appendChild(button);
-        }
-    }
-
-    var language = localStorage.getItem("glean-preferred-language");
-    if (language == null) {
-        language = "Kotlin";
-    }
-
-    switchAllTabs(language);
-}
-
-openTabs()

docs/user/user/focused-use-cases.md

@@ -1,7 +0,0 @@
-# Focused Use Cases
-
-Here is a list of specific examples of using Glean to instrument different situations.
-
-## [Instrumenting Android Crashes With Glean](instrument-android-crashes-example.md)
-
-This is a simple example illustrating a strategy or method for instrumenting crashes in Android applications using Glean.

docs/user/user/index.md

@@ -1,3 +0,0 @@
-# Using the Glean SDK
-
-In this chapter we describe how to use the Glean SDK in your own libraries and applications.

docs/user/user/metrics/adding-new-metrics.md

@@ -8,7 +8,7 @@
 
 When adding a new metric, the process is:
 
-* Consider the question you are trying to answer with this data, and choose the [metric type](metrics/index.md) and parameters to use.
+* Consider the question you are trying to answer with this data, and choose the [metric type](../../reference/metrics/index.md) and parameters to use.
 * Add a new entry to [`metrics.yaml`](#adding-the-metric-to-the-metricsyaml-file).
 * Add code to your project to record into the metric by calling the Glean SDK.
 
@@ -20,45 +20,45 @@ The following is a set of questions to ask about the data being collected to hel
 
 ### Is it a single measurement?
 
-If the value is true or false, use a [boolean metric](metrics/boolean.html).
+If the value is true or false, use a [boolean metric](../../reference/metrics/boolean.html).
 
-If the value is a string, use a [string metric](metrics/string.html). For example, to record the name of the default search engine.
+If the value is a string, use a [string metric](../../reference/metrics/string.html). For example, to record the name of the default search engine.
 
-> **Beware:** string metrics are exceedingly general, and you are probably best served by selecting the most specific metric for the job, since you'll get better error checking and richer analysis tools for free. For example, avoid storing a number in a string metric --- you probably want a [counter metric](metrics/counter.html) instead.
+> **Beware:** string metrics are exceedingly general, and you are probably best served by selecting the most specific metric for the job, since you'll get better error checking and richer analysis tools for free. For example, avoid storing a number in a string metric --- you probably want a [counter metric]../..(/reference/metrics/counter.html) instead.
 
-If you need to store multiple string values in a metric, use a [string list metric](metrics/string_list.html). For example, you may want to record the list of other Mozilla products installed on the device.
+If you need to store multiple string values in a metric, use a [string list metric](../../reference/metrics/string_list.html). For example, you may want to record the list of other Mozilla products installed on the device.
 
-<!-- TODO: If you do know the list of values you might store and you just want to record their presence, consider using a [labeled boolean](metrics/labeled_boolean.html) instead. -->
+<!-- TODO: If you do know the list of values you might store and you just want to record their presence, consider using a [labeled boolean](../../reference/metrics/labeled_boolean.html) instead. -->
 
-<!-- If you have a related set of metrics that you want to record strings for, and you don't know the things the strings relate to at build time, use a [labeled string metric](metrics/labeled_strings.html). -->
+<!-- If you have a related set of metrics that you want to record strings for, and you don't know the things the strings relate to at build time, use a [labeled string metric](../../reference/metrics/labeled_strings.html). -->
 
 For all of the metric types in this section that measure single values, it is especially important to consider how the lifetime of the value relates to the ping it is being sent in. Since these metrics don't perform any aggregation on the client side, when a ping containing the metric is submitted, it will contain only the "last known" value for the metric, potentially resulting in **data loss**.  There is further discussion of [metric lifetimes](#when-should-the-glean-sdk-automatically-clear-the-measurement) below.
 
 ### Are you counting things?
 
-If you want to know how many times something happened, use a [counter metric](metrics/counter.html).  If you are counting a group of related things, or you don't know what all of the things to count are at build time, use a [labeled counter metric](metrics/labeled_counters.html).
+If you want to know how many times something happened, use a [counter metric](../../reference/metrics/counter.html).  If you are counting a group of related things, or you don't know what all of the things to count are at build time, use a [labeled counter metric](../../reference/metrics/labeled_counters.html).
 
 If you need to know how many times something happened relative to the number of times something else happened,
-use a [rate metric](metrics/rate.html).
+use a [rate metric](../../reference/metrics/rate.html).
 
-If you need to know when the things being counted happened relative to other things, consider using an [event](metrics/event.html).
+If you need to know when the things being counted happened relative to other things, consider using an [event](../../reference/metrics/event.html).
 
 ### Are you measuring time?
 
-If you need to record an absolute time, use a [datetime metric](metrics/datetime.html). Datetimes are recorded in the user's local time, according to their device's real time clock, along with a timezone offset from UTC. Datetime metrics allow specifying the resolution they are collected at, and to stay [lean][lean-data], they should only be collected at the minimum resolution required to answer your question.
+If you need to record an absolute time, use a [datetime metric](../../reference/metrics/datetime.html). Datetimes are recorded in the user's local time, according to their device's real time clock, along with a timezone offset from UTC. Datetime metrics allow specifying the resolution they are collected at, and to stay [lean][lean-data], they should only be collected at the minimum resolution required to answer your question.
 
 If you need to record how long something takes you have a few options.
 
-If you need to measure the total time spent doing a particular task, look to the [timespan metric](metrics/timespan.html). Timespan metrics allow specifying the resolution they are collected at, and to stay [lean][lean-data], they should only be collected at the minimum resolution required to answer your question.
+If you need to measure the total time spent doing a particular task, look to the [timespan metric](../../reference/metrics/timespan.html). Timespan metrics allow specifying the resolution they are collected at, and to stay [lean][lean-data], they should only be collected at the minimum resolution required to answer your question.
 Note that this metric should only be used to measure time on a single thread. If multiple overlapping timespans are measured for the same metric, an invalid state error is recorded.
 
-If you need to measure the relative occurrences of many timings, use a [timing distribution](metrics/timing_distribution.html). It builds a histogram of timing measurements, and is safe to record multiple concurrent timespans on different threads.
+If you need to measure the relative occurrences of many timings, use a [timing distribution](../../reference/metrics/timing_distribution.html). It builds a histogram of timing measurements, and is safe to record multiple concurrent timespans on different threads.
 
-If you need to know the time between multiple distinct actions that aren't a simple "begin" and "end" pair, consider using an [event](metrics/event.html).
+If you need to know the time between multiple distinct actions that aren't a simple "begin" and "end" pair, consider using an [event](../../reference/metrics/event.html).
 
 ### Do you need to know the order of events relative to other events?
 
-If you need to know the order of actions relative to other actions, such as, the user performed tasks A, B, and then C, and this is meaningfully different from the user performing tasks A, C and then B, (in other words, the order is meaningful beyond just the *fact* that a set of tasks were performed), use an [event metric](metrics/event.html).
+If you need to know the order of actions relative to other actions, such as, the user performed tasks A, B, and then C, and this is meaningfully different from the user performing tasks A, C and then B, (in other words, the order is meaningful beyond just the *fact* that a set of tasks were performed), use an [event metric](../../reference/metrics/event.html).
 
 > **Important:** events are the most expensive metric type to record, transmit, store and analyze, so they should be used sparingly, and only when none of the other metric types are sufficient for answering your question.
 
@@ -81,13 +81,13 @@ If the metric is still needed after its expiration date, it should go back for [
 
 The `lifetime` parameter of a metric defines when its value will be cleared. There are three lifetime options available:
 
-{{#include lifetimes-parameters.md}}
+{{#include ../../_includes/lifetimes-parameters.md}}
 
 While lifetimes are important to understand for all metric types, they are particularly important for the metric types that record single values and don't aggregate on the client (`boolean`, `string`, `labeled_string`, `string_list`, `datetime` and `uuid`), since these metrics will send the "last known" value and missing the earlier values could be a form of unintended data loss.
 
 ### A lifetime example
 
-Let's work through an example to see how these lifetimes play out in practice. Let's suppose we have a user preference, "turbo mode", which defaults to `false`, but the user can turn it to `true` at any time.  We want to know when this flag is `true` so we can measure its affect on other metrics in the same ping.  In the following diagram, we look at a time period that sends 4 pings across two separate runs of the application. We assume here, that like the Glean SDK's built-in [metrics ping](pings/metrics.html), the developer writing the metric isn't in control of when the ping is submitted.
+Let's work through an example to see how these lifetimes play out in practice. Let's suppose we have a user preference, "turbo mode", which defaults to `false`, but the user can turn it to `true` at any time.  We want to know when this flag is `true` so we can measure its affect on other metrics in the same ping.  In the following diagram, we look at a time period that sends 4 pings across two separate runs of the application. We assume here, that like the Glean SDK's built-in [metrics ping](../pings/metrics.html), the developer writing the metric isn't in control of when the ping is submitted.
 
 In this diagram, the ping measurement windows are represented as rectangles, but the moment the ping is "submitted" is represented by its right edge. The user changes the "turbo mode" setting from `false` to `true` in the first run, and then toggles it again twice in the second run.
   
@@ -105,11 +105,11 @@ In this diagram, the ping measurement windows are represented as rectangles, but
 
 - **F. User, set on init and change**: Since `user` lifetime metrics aren't cleared unless the user profile is reset, it is included in all subsequent pings.  This would be true even if the "turbo mode" preference were never changed again.
 
-Note that for all of the metric configurations, the toggle of the preference off and on during Ping 4 is completely missed.  If you need to create a ping containing one, and only one, value for this metric, consider using a [custom ping](pings/custom.html) to create a ping whose lifetime matches the lifetime of the value.
+Note that for all of the metric configurations, the toggle of the preference off and on during Ping 4 is completely missed.  If you need to create a ping containing one, and only one, value for this metric, consider using a [custom ping](../pings/custom.html) to create a ping whose lifetime matches the lifetime of the value.
 
 ### What if none of these lifetimes are appropriate?
 
-If the timing at which the metric is sent in the ping needs to closely match the timing of the metrics value, the best option is to use a [custom ping](pings/custom.html) to manually control when pings are sent.
+If the timing at which the metric is sent in the ping needs to closely match the timing of the metrics value, the best option is to use a [custom ping](../pings/custom.html) to manually control when pings are sent.
 
 This is especially useful when metrics need to be tightly related to one another, for example when you need to measure the distribution of frame paint times when a particular rendering backend is in use.  If these metrics were in different pings, with different measurement windows, it is much harder to do that kind of reasoning with much certainty.
 
@@ -142,7 +142,7 @@ For example, if defining a set of events related to search, put them in a catego
 
 The current set of metrics the Glean SDK supports is based on known common use cases, but new use cases are discovered all the time.
 
-Please reach out to us on [#glean:mozilla.org](https://chat.mozilla.org/#/room/#glean:mozilla.org). If you think you need a new metric type, we [have a process for that](metrics/index.html#adding-or-changing-metric-types).
+Please reach out to us on [#glean:mozilla.org](https://chat.mozilla.org/#/room/#glean:mozilla.org). If you think you need a new metric type, we [have a process for that](../../reference/metrics/index.html#adding-or-changing-metric-types).
 
 ## How do I make sure my metric is working?
 
@@ -169,7 +169,7 @@ The overall organization is:
 
 ```YAML
 # Required to indicate this is a `metrics.yaml` file
-$schema: moz://mozilla.org/schemas/glean/metrics/2-0-0
+$schema: moz://mozilla.org/schemas/glean/../../reference/metrics/2-0-0
 
 toolbar:
   click:
@@ -192,13 +192,13 @@ Categories can have `.` characters to provide extra structure, for example `cate
 
 Metric names have a maximum length of 30 characters.
 
-The details of the metric parameters are described in [metric parameters](metric-parameters.md).
+The details of the metric parameters are described in [metric parameters](../../reference/yaml/index.md).
 
 The `metrics.yaml` file is used to generate code in the target language (e.g. Kotlin, Swift, ...) that becomes the public API to access your application's metrics.
 
 ## Using the metric from your code
 
-The [reference documentation for each metric type](metrics/index.html) goes into detail about using each metric type from your code.
+The [reference documentation for each metric type](../../reference/metrics/index.html) goes into detail about using each metric type from your code.
 
 Note that all Glean metrics are write-only. Outside of unit tests, it is impossible to retrieve a value from the Glean SDK's database.
 While this may seem limiting, this is required to:
@@ -209,7 +209,7 @@ While this may seem limiting, this is required to:
 
 One thing to note is that we try to adhere to the coding conventions of each language wherever possible, to the metric name in the `metrics.yaml` (which is in `snake_case`) may be changed to some other case convention, such as `camelCase`, when used from code.
 
-{{#include ../../shared/tab_header.md}}
+{{#include ../../../shared/tab_header.md}}
 
 <div data-lang="Kotlin" class="tab">
 
@@ -267,6 +267,6 @@ TODO. To be implemented in [this bug](https://bugzilla.mozilla.org/show_bug.cgi?
 
 </div>
 
-{{#include ../../shared/tab_footer.md}}
+{{#include ../../../shared/tab_footer.md}}
 
 [lean-data]: https://www.mozilla.org/en-US/about/policy/lean-data/stay-lean/

docs/user/user/metrics/error-reporting.md

@@ -3,7 +3,7 @@
 The Glean SDK records the number of errors that occur when metrics are passed invalid data or are otherwise used incorrectly.
 This information is reported back in special labeled counter metrics in the `glean.error` category.
 Error metrics are included in the same pings as the metric that caused the error.
-Additionally, error metrics are always sent in the [`metrics` ping](pings/metrics.md) ping.
+Additionally, error metrics are always sent in the [`metrics` ping](../pings/metrics.md) ping.
 
 The following categories of errors are recorded:
 

docs/user/user/metrics/index.md

@@ -1,78 +1,3 @@
 # Metrics
 
-> **Not sure which metric type to use?** These docs contain a [series of questions](../adding-new-metrics.html#choosing-a-metric-type) that can help. Reference information about each metric type is linked below.
-
-The parameters available that apply to any metric type are in the [metric parameters page](../metric-parameters.html).
-
-There are different metrics to choose from, depending on what you want to achieve:
-
-* [Boolean](boolean.md): Records a single truth value, for example "is a11y enabled?"
-
-* [Labeled boolean](labeled_booleans.md): Records truth values for a set of labels, for example "which a11y features are enabled?"
-
-* [Counter](counter.md): Used to count how often something happens, for example, how often a certain button was pressed.
-
-* [Labeled counter](labeled_counters.md): Used to count how often something happens, for example which kind of crash occurred (`"uncaught_exception"` or `"native_code_crash"`).
-
-* [String](string.md): Records a single Unicode string value, for example the name of the OS.
-
-* [Labeled strings](labeled_strings.md): Records multiple Unicode string values, for example to record which kind of error occurred in different stages of a login process.
-
-* [String List](string_list.md): Records a list of Unicode string values, for example the list of enabled search engines.
-
-* [Timespan](timespan.md): Used to measure how much time is spent in a single task.
-
-* [Timing Distribution](timing_distribution.md): Used to record the distribution of multiple time measurements.
-
-* [Memory Distribution](memory_distribution.md): Used to record the distribution of memory sizes.
-
-* [UUID](uuid.md): Used to record universally unique identifiers (UUIDs), such as a client ID.
-
-* [Datetime](datetime.md): Used to record an absolute date and time, such as the time the user first ran the application.
-
-* [Events](event.md): Records events e.g. individual occurrences of user actions, say every time a view was open and from where.
-
-* [Quantity](quantity.md): Used to record a single non-negative integer value. For example, the width of the display in pixels.
-
-* [Rate](rate.md): Used to record the rate something happens relative to some other thing.
-  For example, the number of HTTP connections that experienced an error relative to the number of total HTTP connections made.
-
-* [Custom Distribution](custom_distribution.md): Used to record the distribution of a value that needs fine-grained control of how the histogram buckets are computed.  **Custom distributions are only available for values that come from Gecko.**
-
-## Labeled metrics
-
-There are two types of metrics listed above - *labeled* and *unlabeled* metrics. If a metric is *labeled*, it means that for a single metric entry you define in `metrics.yaml`, you can record into multiple metrics under the same name, each of the same type and identified by a different string label.
-
-This is useful when you need to break down metrics by a label known at build time or run time. For example:
-
-- When you want to count a different set of sub-views that users interact with, you could use `viewCount["view1"].add()` and `viewCount["view2"].add()`.
-
-- When you want to count errors that might occur for a feature, you could use `errorCount[errorName].add()`.
-
-Labeled metrics come in two forms:
-
-- **Static labels**: The labels are specified at build time in the `metrics.yaml` file, in the `labels` parameter.
-  If a label that isn't part of this set is used at run time, it is converted to the special label `__other__`.
-  The number of static labels is limited to 100 per metric.
-
-- **Dynamic labels**: The labels aren't known at build time, so are set at run time.
-  Only the first 16 labels seen by the Glean SDK will be tracked. After that, any additional labels are converted to the special label `__other__`.
-
-> **Note**: Be careful with using arbitrary strings as labels and make sure they can't accidentally contain identifying data (like directory paths or user input).
-
-### Label format
-
-To ensure maximum support in database columns, labels must be made up of dot-separated identifiers with lowercase ASCII alphanumerics, containing underscores and dashes.
-
-Specifically, they must conform to this regular expression:
-
-```
-^[a-z_][a-z0-9_-]{0,29}(\\.[a-z_][a-z0-9_-]{0,29})*$
-```
-
-## Adding or changing metric types
-Glean has a [well-defined process](https://wiki.mozilla.org/Glean/Adding_or_changing_Glean_metric_types) for requesting changes to existing metric types or suggesting the implementation of new metric types:
-
-1.  Glean consumers need to file a bug in the [Data platforms & tools::Glean Metric Types](https://bugzilla.mozilla.org/enter_bug.cgi?product=Data%20Platform%20and%20Tools&component=Glean%20Metric%20Types) component, filling in the provided form;
-2.  The triage owner of the Bugzilla component prioritizes this within 6 business days and kicks off the [decision making process](https://wiki.mozilla.org/Glean/Adding_or_changing_Glean_metric_types#The_decision_making_process).
-3.  Once the decision process is completed, the bug is closed with a comment outlining the decision that was made.
+In this chapter we describe how to define and use the Glean SDK's metrics.

docs/user/user/metrics/testing-metrics.md

@@ -10,7 +10,7 @@ To encourage using the testing API, it is also possible to [generate testing cov
 
 ## General test API method semantics
 
-{{#include ../../shared/tab_header.md}}
+{{#include ../../../shared/tab_header.md}}
 
 <div data-lang="Kotlin" class="tab">
 
@@ -18,7 +18,7 @@ Using the Glean SDK's unit testing API requires adding [Robolectric 4.0 or later
 
 ```groovy
 dependencies {
-    testImplementation "org.robolectric:robolectric:4.3.1" 
+    testImplementation "org.robolectric:robolectric:4.3.1"
 }
 ```
 
@@ -161,13 +161,13 @@ TODO. To be implemented in [bug 1648448](https://bugzilla.mozilla.org/show_bug.c
 
 </div>
 
-{{#include ../../shared/tab_footer.md}}
+{{#include ../../../shared/tab_footer.md}}
 
 ## Testing metrics for custom pings
 
 In order to test metrics where the metric is included in more than one ping, the test functions take an optional `pingName` argument (`ping_name` in Python).
-This is the name of the ping that the metric is being sent in, such as `"events"` for the [`events` ping](pings/events.md),
-or `"metrics"` for the [`metrics` ping](pings/metrics.md).
+This is the name of the ping that the metric is being sent in, such as `"events"` for the [`events` ping](../pings/events.md),
+or `"metrics"` for the [`metrics` ping](../pings/metrics.md).
 This could also be a custom ping name that the metric is being sent in.
 In most cases you should not have to supply the ping name to the test function and can just use the default which is the "default" ping that this metric is sent in.
 You should only need to provide a `pingName` if the metric is being sent in more than one ping in order to identify the correct metric store.
@@ -181,7 +181,7 @@ GleanMetrics.Foo.uriCount.testGetValue("customPing")
 
 ## Example of using the test API
 
-{{#include ../../shared/tab_header.md}}
+{{#include ../../../shared/tab_header.md}}
 
 <div data-lang="Kotlin" class="tab">
 
@@ -267,7 +267,7 @@ TODO. To be implemented in [bug 1648448](https://bugzilla.mozilla.org/show_bug.c
 
 </div>
 
-{{#include ../../shared/tab_footer.md}}
+{{#include ../../../shared/tab_footer.md}}
 
 ## Generating testing coverage reports