Merge pull request #2636 from reubenmiller/docs-reshuffle-docs

docs: cleanup and normalization

docs/src/contribute/BUILDING.md → docs/src/contribute/build.md

@@ -1,10 +1,10 @@
 ---
-title: Build thin-edge
+title: Build
 tags: [Contribute, Build]
-sidebar_position: 1
+description: Build %%te%% from the source code
 ---
 
-# Building thin-edge.io
+This page details how to build %%te%% from the source code.
 
 ## Requirements
 
@@ -26,7 +26,7 @@ A list of our test platforms can be found [here](../references/supported-platfor
 
 ## Get the code
 
-thin-edge.io code is in git repository on github to acquire the code use following command:
+%%te%% code is in git repository on github to acquire the code use following command:
 
 * via SSH:
 
@@ -71,13 +71,13 @@ For other shells, you'll want to find the appropriate place to set a configurati
 eg. zsh uses `~/.zshrc`. Check your shell's documentation to find what file it uses.
 :::
 
-thin-edge.io operates the `MSRV` (Minimum Supported Rust Version) and uses stable toolchain.
+%%te%% operates the `MSRV` (Minimum Supported Rust Version) and uses stable toolchain.
 
 Current MSRV is `1.65`.
 
 ### Cross compilation toolchain (optional)
 
-thin-edge.io can be compiled for target architecture on non-target device, this is called cross compilation.
+%%te%% can be compiled for target architecture on non-target device, this is called cross compilation.
 Currently we support `Raspberry Pi 3B` for `armv7` architecture with Rust's cross compilation toolchain called [cargo cross](https://github.com/rust-embedded/cross).
 
 To install [cargo cross](https://github.com/rust-embedded/cross):
@@ -105,7 +105,7 @@ just release-linux-virtual
 
 ## Compiling
 
-To build thin-edge.io we are using `cargo`.
+To build %%te%% we are using `cargo`.
 
 As we are using  `cargo workspace` for all our crates. All compiled files are put in `./target/` directory with target's name eg: `./target/debug` or `./target/release` for native builds and for cross compiled targets `./target/<architecture>/debug` or `./target/<architecture>/release` dependent on the target of the build.
 
@@ -158,7 +158,7 @@ Binaries can be run eg: `./target/release/tedge`.
 
 ## Building deb package
 
-Currently thin-edge.io contains 2 binaries, `tedge` (cli) and `tedge-mapper` which are packaged as separate debian packages. To create following commands are to be issued:
+Currently %%te%% contains 2 binaries, `tedge` (cli) and `tedge-mapper` which are packaged as separate debian packages. To create following commands are to be issued:
 
 ```sh
 cargo deb -p tedge
@@ -204,7 +204,7 @@ cross build --target armv7-unknown-linux-gnueabihf --release
 
 ## Running tests
 
-When contributing to thin-edge.io we ask you to write tests for the code you have written. The tests will be run by build pipeline when you create pull request, but you can easily run all the tests when you are developing with following command:
+When contributing to %%te%% we ask you to write tests for the code you have written. The tests will be run by build pipeline when you create pull request, but you can easily run all the tests when you are developing with following command:
 
 ```sh
 cargo test

docs/src/contribute/design/index.md

@@ -1,11 +1,10 @@
 ---
 title: Design
 tags: [Documentation, next]
-sidebar_position: 1
 ---
 
 import DocCardList from '@theme/DocCardList';
 
-The following pages describe important design elements of thin-edge.
+The following pages describe important design elements of %%te%%.
 
 <DocCardList />

docs/src/contribute/design/mqtt-topic-design.md

@@ -63,7 +63,7 @@ The above topic schema uses fixed positions to indicate the entity type, e.g. to
 A service represents an entity that has dependence on a device. For example a service is running on device, and therefore can not exist on its own. The lifecycle of the service is linked to the device it is running on, so when the device is removed, then the service is also removed.
 :::
 
-The `<device_id>` can be either set to `main`, which represents the thin-edge device, or to a id/name used to represent a child device. Telemetry data targeted to the main or child devices, require the `service` and `<service_id>` segments to be set to an empty string.
+The `<device_id>` can be either set to `main`, which represents the %%te%% device, or to a id/name used to represent a child device. Telemetry data targeted to the main or child devices, require the `service` and `<service_id>` segments to be set to an empty string.
 
 The following table shows some examples showing the relationship between the topic and the entity/component.
 

docs/src/contribute/index.md

@@ -1,12 +1,12 @@
 ---
-title: Contribute to thin-edge
+title: Contribute to thin-edge.io
 tags: [Contribute]
 sidebar_position: 5
 ---
 
 import DocCardList from '@theme/DocCardList';
 
-This section is for who wants to contribute to thin-edge,
+This section is for who wants to contribute to %%te%%,
 submitting issues, writing documentation, implementing features.
 
 <DocCardList />

docs/src/contribute/DEBIAN_PACKAGE_HOSTING.md → docs/src/contribute/package-hosting.md

@@ -1,16 +1,14 @@
 ---
-title: Debian Package Hosting
+title: Package Hosting
 tags: [Contribute, Packaging]
-sidebar_position: 3
+description: Package hosting of %%te%% components
 ---
 
-# Debian Package Hosting
-
-In additional to the thin-edge.io install script, the packages are also publicly hosted APT repository.
+In additional to the %%te%% install script, the packages are also publicly hosted APT repository.
 
 ## Official releases
 
-The following APT repositories contain the official releases of thin-edge.io. The packages will have a nice `x.y.z` version number, and all of the packages go through our full suite of automated and manual testing.
+The following APT repositories contain the official releases of %%te%%. The packages will have a nice `x.y.z` version number, and all of the packages go through our full suite of automated and manual testing.
 
 The packages are the same ones which are uploaded to the [GitHub Releases](https://github.com/thin-edge/thin-edge.io/releases) page.
 
@@ -45,7 +43,7 @@ curl -1sLf \
 
 ## Pre releases
 
-The latest built packages from the `main` branch of the project. The packages go through the same automated testing process as the official releases, however they are not tagged in git, so the version numbers will look like `0.8.1-171-ga72e5432` (see the [Version syntax](./DEBIAN_PACKAGE_HOSTING.md#version-syntax) for description about the version).
+The latest built packages from the `main` branch of the project. The packages go through the same automated testing process as the official releases, however they are not tagged in git, so the version numbers will look like `0.8.1-171-ga72e5432` (see the [Version syntax](#version-syntax) for description about the version).
 
 These repositories allow you to test new features as they get merged to `main`, rather than waiting for the official release. However it is still advised to only use these repositories for development and testing purposes as the official versions go through additional testing.
 
@@ -101,7 +99,7 @@ curl -1sLf \
 
 ## Removing the APT repositories
 
-All of the `thin-edge.io` apt repositories can be removed by the following command.
+All of the %%te%% apt repositories can be removed by the following command.
 
 ```sh
 sudo rm -f /etc/apt/sources.list.d/thinedge-tedge-*.list
@@ -110,7 +108,7 @@ sudo rm -rf /var/lib/apt/lists/*
 sudo apt-get update
 ```
 
-## Version syntax
+## Version syntax {#version-syntax}
 
 The version is automatically generated from the source code management tool, git. The version is based on the commit used to build the packages and its distance from the last tag (e.g. the last official released version).
 

docs/src/contribute/INSTALLING_DOCKER.md → docs/src/contribute/setting-up-docker.md

@@ -1,12 +1,9 @@
 ---
 title: Setting up Docker
 tags: [Contribute]
-sidebar_position: 10
 ---
 
-# Setting up Docker (OSS - Variant)
-
-This guide is to assist with the installation of docker and some of the docker cli tools. It is not meant to replace other online articles but more of a cheat sheet to getting your setup up and running as fast as possible. If you encounter issues with the setup, please search online for a fix.
+This guide is to assist with the installation of docker (OSS Variant) and some of the docker cli tools. It is not meant to replace other online articles but more of a cheat sheet to getting your setup up and running as fast as possible. If you encounter issues with the setup, please search online for a fix.
 
 ## Installation
 

docs/src/contribute/DEV_CONTAINER.md → docs/src/contribute/vscode-dev-containers.md

@@ -1,11 +1,8 @@
 ---
 title: VSCode Dev Containers
 tags: [Contribute]
-sidebar_position: 2
 ---
 
-# VSCode Dev Containers
-
 VSCode Dev Containers are great for developing as they contain all of the project's dependencies and in the end you have a ready-to-use dockerFile which can also be used in your CI/CD pipeline.
 
 It provides a normalized experience to all VSCode users across MacOS, Windows and Linux. All you need to get going is a the open source docker engine (not Docker Desktop!) and docker-compose.
@@ -18,7 +15,7 @@ Before VSCode Dev container can be used, you need to install a few things.
 
 1. Install `docker` and `docker-compose` if you do not already have these
 
-    Checkout the [INSTALLING_DOCKER](./INSTALLING_DOCKER.md) instructions to help guide you
+    Checkout the [INSTALLING_DOCKER](./setting-up-docker.md) instructions to help guide you
 
 1. Install VSCode and make sure it is up to date
 
@@ -60,7 +57,7 @@ But in both methods it is recommended to fork the project first, then clone from
 
 1. Open a terminal
 
-2. Clone the forked thin-edge.io project
+2. Clone the forked %%te%% project
 
     **Example**
 
@@ -94,7 +91,7 @@ But in both methods it is recommended to fork the project first, then clone from
 
 2. Click on the `Remote Explorer` Icon on the left hand navigation menu (the icon looks like a computer monitor)
 
-3. From the `Dev Containers` section, right-click on the thin-edge.io dev container, and select `Open Folder in Container`
+3. From the `Dev Containers` section, right-click on the %%te%% dev container, and select `Open Folder in Container`
 
 
 ## Rebuilding the dev container

docs/src/contribute/writing-documentation/index.md

@@ -1,5 +1,5 @@
 ---
-title: Writing documentation
+title: Writing Documentation
 tags: [Documentation]
 ---
 

docs/src/contribute/writing-documentation/markdown-components.md

@@ -1,5 +1,5 @@
 ---
-title: Markdown components
+title: Markdown Components
 tags: [Documentation]
 sidebar_position: 1
 ---
@@ -197,7 +197,7 @@ tedge disconnect aws
 
 ## MQTT Code block
 
-One of the main interfaces for thin-edge.io is MQTT, therefore a special plugin has been created to display how to publish/subscribe to messages on an MQTT broker.
+One of the main interfaces for %%te%% is MQTT, therefore a special plugin has been created to display how to publish/subscribe to messages on an MQTT broker.
 
 The code block only expects the writer to provide the `tedge mqtt ...` command, and the plugin will take care of the translation to the various formats. The decision was made to use the `tedge mqtt` command as the base format so that the code blocks would also still be useful when viewing the raw markdown documents.
 

docs/src/contribute/writing-documentation/markdown-guidelines.md

@@ -1,5 +1,5 @@
 ---
-title: Markdown guidelines
+title: Markdown Guidelines
 tags: [Documentation]
 sidebar_position: 2
 ---

docs/src/extend/firmware-management/building-image/index.md

@@ -6,6 +6,6 @@ sidebar_position: 1
 
 import DocCardList from '@theme/DocCardList';
 
-Instructions on how to build different Operation System images with thin-edge.io setup to perform Over-the-Air (OTA) updates of the operating system.
+Instructions on how to build different Operation System images with %%te%% setup to perform Over-the-Air (OTA) updates of the operating system.
 
 <DocCardList />

docs/src/extend/firmware-management/building-image/rugpi/index.md

@@ -6,7 +6,7 @@ sidebar_position: 1
 
 import DocCardList from '@theme/DocCardList';
 
-Guides to building custom thin-edge.io based images using [Rugpi](https://github.com/silitics/rugpi). The images produced support Over-the-Air (OTA) Operating System updates.
+Guides to building custom %%te%% based images using [Rugpi](https://github.com/silitics/rugpi). The images produced support Over-the-Air (OTA) Operating System updates.
 
 Currently Rugpi only supports Raspberry Pi devices, however this maybe expanded upon in the future.
 

docs/src/extend/firmware-management/building-image/yocto/index.md

@@ -6,6 +6,6 @@ sidebar_position: 1
 
 import DocCardList from '@theme/DocCardList';
 
-Guides to building custom thin-edge.io based images using [The Yocto Project](https://www.yoctoproject.org/). The images produced support Over-the-Air (OTA) Operating System updates using proven technologies such as mender.
+Guides to building custom %%te%% based images using [The Yocto Project](https://www.yoctoproject.org/). The images produced support Over-the-Air (OTA) Operating System updates using proven technologies such as mender.
 
 <DocCardList />

docs/src/extend/firmware-management/building-image/yocto/tutorial.md

@@ -48,8 +48,8 @@ The project uses different Yocto layers to build an image which contains:
 |Item|Description|
 |--|--|
 |Yocto Linux Distribution|Base operating system|
-|thin-edge.io|thin-edge.io and all of its components|
-|thin-edge.io mender workflow|A workflow definition to perform Operation System A/B updates, e.g. mender commit or rollback|
+|thin-edge.io|%%te%% and all of its components|
+|%%te%% mender workflow|A workflow definition to perform Operation System A/B updates, e.g. mender commit or rollback|
 |mender|mender binary configured in standalone mode|
 
 ### Cloning the project

docs/src/extend/firmware-management/device-onboarding.md

@@ -2,9 +2,10 @@
 title: Onboarding a Device
 tags: [Extend, Build]
 sidebar_position: 5
+description: Connecting devices to the cloud for the first time
 ---
 
-Onboarding a new devices involves configuring thin-edge.io to connect to a cloud for the first time. This generally involves the following steps:
+Onboarding a new devices involves configuring %%te%% to connect to a cloud for the first time. This generally involves the following steps:
 
 1. Configure the cloud url to connect to
 2. Generate the device certificate (if it does not already exist)

docs/src/extend/firmware-management/index.md

@@ -6,6 +6,6 @@ sidebar_position: 1
 
 import DocCardList from '@theme/DocCardList';
 
-Instructions on how to build different Operation System images with thin-edge.io setup to perform Over-the-Air (OTA) updates of the operating system.
+Instructions on how to build different Operation System images with %%te%% setup to perform Over-the-Air (OTA) updates of the operating system.
 
 <DocCardList />

docs/src/extend/index.md

@@ -1,12 +1,12 @@
 ---
-title: Extend thin-edge
+title: Extend thin-edge.io
 tags: [Extend]
 sidebar_position: 4
 ---
 
 import DocCardList from '@theme/DocCardList';
 
-This section is for the agent developers who want to adapt and extend thin-edge
+This section is for the agent developers who want to adapt and extend %%te%%
 to meet the requirements of their domain application, target devices and cloud.
 
 <DocCardList />

docs/src/extend/write-my-software-management-plugin.md → docs/src/extend/software-management.md

@@ -1,15 +1,14 @@
 ---
-title: Software Management Plugin
+title: Software Management
 tags: [Extend, Software Management]
 sidebar_position: 1
+description: How to create a custom software management plugin
 ---
 
-# Write my software management plugin
-
-**thin-edge.io** Software Management natively supports APT (Debian) packages.
+%%te%% Software Management natively supports APT (Debian) packages.
 However, there are many package management systems in the world,
 and you may want to have a plugin that is suitable for your device.
-For such a demand, we provide the [**Package Manager Plugin API**](./../references/plugin-api.md)
+For such a demand, we provide the [**Package Manager Plugin API**](./../references/software-management-plugin-api.md)
 to write a custom Software Management plugin in your preferred programming language.
 
 In this tutorial, we will look into the **Package Manager Plugin API**,
@@ -418,5 +417,5 @@ That example exists immediately if one of the commands fails.
 
 Additional information and examples can be found from the following references:
 
-- [Package Manager Plugin API Specification](https://github.com/thin-edge/thin-edge.io/blob/main/docs/src/references/plugin-api.md).
+- [Package Manager Plugin API Specification](https://github.com/thin-edge/thin-edge.io/blob/main/docs/src/references/software-management-plugin-api.md).
 - [tedge-apt-plugin (Debian APT Plugin)](https://github.com/thin-edge/thin-edge.io/tree/main/plugins/tedge_apt_plugin) written in Rust.