mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-11-09 23:24:10 -08:00
Merge pull request #236 from jfirwin/about-documentation
about-documentation additions
This commit is contained in:
Foster Irwin
GitHub
commit
5eb03b78d7
|
|
@ -48,7 +48,7 @@ nodejs is required in your dev. environment. The method for installing nodejs de
|
|||
Fork then clone the repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.co/meshtastic/meshtastic
|
||||
git clone https://github.com/meshtastic/meshtastic
|
||||
```
|
||||
|
||||
|
||||
|
|
|
|||
10
docs/about-documentation/docusaurus.md
Normal file
10
docs/about-documentation/docusaurus.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
---
|
||||
id: docusaurus
|
||||
title: Docusaurus
|
||||
sidebar_label: Docusaurus
|
||||
---
|
||||
## Overview
|
||||
Meshtastic's documentation is set up using [Docusaurus](https://docusaurus.io). It is highly encouraged to look at [their documentation](https://docusaurus.io/docs) when looking for a solution to a problem with our docs. They most likely have thought of the use case you've discovered.
|
||||
|
||||
## Known Issues
|
||||
- Admonitions within a `TabItem` component need to be completely unindented to show up correctly.
|
||||
11
docs/about-documentation/github.md
Normal file
11
docs/about-documentation/github.md
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
---
|
||||
id: github
|
||||
title: GitHub
|
||||
sidebar_label: GitHub
|
||||
---
|
||||
## Overview
|
||||
All of Meshtastic's code and documentation is hosted on GitHub. If you would like to contribute to the project, having a GitHub account is an important step to doing so.
|
||||
|
||||
## Set up GitHub account
|
||||
- Go to [github.com](https://github.com)
|
||||
- Click `Sign Up`
|
||||
|
|
@ -7,9 +7,11 @@ slug: /about-documentation
|
|||
Meshtastic documentation is an important ingredient to the overall project. We want users to hit the ground running with the information they need right at their finger tips. This section will discuss the documentation software stack, file organization, and style guides.
|
||||
|
||||
## Software Stack
|
||||
Our documentation is powered by [Docusaurus](https://docusaurus.io) — a documentation platform built on React that utilizes markdown files. Because markdown files are easy to edit, most content changes should be fairly simple.
|
||||
All of our documentation resides on GitHub. Instructions for setting up your GitHub account are located [here](about-documentation/github).
|
||||
|
||||
Another component that we use is [Vercel](https://vercel.com) — a platform for frontend frameworks and static sites.
|
||||
Our documentation is powered by [Docusaurus](https://docusaurus.io) — a documentation platform built on React that utilizes markdown files. Because markdown files are easy to edit, most content changes should be fairly simple. Instructions for setting up your instance of Docusaurus are located [here](about-documentation/docusaurus).
|
||||
|
||||
Another component that we use is [Vercel](https://vercel.com) — a platform for frontend frameworks and static sites. Instructions for setting up your instance of Vercel are located [here](about-documentation/vercel).
|
||||
|
||||
## Documentation Organization
|
||||
| Section | File Path | Description |
|
||||
|
|
@ -22,3 +24,34 @@ Another component that we use is [Vercel](https://vercel.com) — a platform for
|
|||
| Contribute to Meshtastic | `docs/developers` | Details each of the projects and how they work together to give a developer an idea of how the Meshtastic ecosystem operates. |
|
||||
| About the Documentation | `docs/about-documentation` | This section explains how our documentation is organized, how to make edits to the documentation, view a local copy of your fork of the project. Style guides and tips will also be included here. |
|
||||
| Legal | `docs/legal` | Any legal information. Most changes here will be handled by developers actually working on the projects that require any legal disclosures. Examples include: the Meshtastic trademark, terms of service, and privacy policy. |
|
||||
|
||||
## Quick Start
|
||||
|
||||
Assuming you have the [prerequisites installed](about-documentation/serve-docs-locally#prerequisites), running a local instance of Docusaurus takes three steps:
|
||||
|
||||
1. Fork/Clone the [meshtastic/Meshtastic](https://github.com/meshtastic/Meshtastic) repository and navigate to the root directory of the project.
|
||||
```bash title="Clone the project"
|
||||
git clone https://github.com/meshtastic/Meshtastic.git
|
||||
```
|
||||
```bash title="Clone fork of the project"
|
||||
git clone https://github.com/[username]/Meshtastic.git
|
||||
```
|
||||
```bash title="Change Directory"
|
||||
cd ~/Meshtastic
|
||||
```
|
||||
2. Install Dependencies
|
||||
```bash title="Install dependencies using Yarn"
|
||||
yarn install
|
||||
```
|
||||
3. Run Docusaurus
|
||||
```bash title="Run node.js server"
|
||||
yarn start
|
||||
```
|
||||
|
||||
:::tip
|
||||
Before submitting a pull request, it's helpful to run the following command to ensure there are no broken links or errors:
|
||||
|
||||
```bash title="Build Project"
|
||||
yarn build
|
||||
```
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -12,6 +12,7 @@ In order to set up your local environment, you will need to install:
|
|||
- [Node & Node package manager (NPM)](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
|
||||
- [Yarn package manager](https://yarnpkg.com/getting-started/install)
|
||||
|
||||
## Getting Started
|
||||
### Fork the Meshtastic Repository
|
||||
|
||||
Log into Github and create a fork of the [meshtastic/Meshtastic](https://github.com/meshtastic/Meshtastic) repository.
|
||||
|
|
@ -40,3 +41,11 @@ yarn install
|
|||
```bash title="Run node.js server"
|
||||
yarn start
|
||||
```
|
||||
|
||||
:::tip
|
||||
Before submitting a pull request, it's helpful to run the following command to ensure there are no broken links or errors:
|
||||
|
||||
```bash title="Build Project"
|
||||
yarn build
|
||||
```
|
||||
:::
|
||||
|
|
|
|||
95
docs/about-documentation/style-guides/settings.md
Normal file
95
docs/about-documentation/style-guides/settings.md
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
---
|
||||
id: style-guide-settings
|
||||
title: Style Guide - Settings Pages
|
||||
sidebar_label: Settings Pages
|
||||
---
|
||||
## Overview
|
||||
Setting pages should focus solely on settings and configuring the device. Hardware is often a related topic, however these pages should not attempt to explain attaching hardware. Mention that hardware is required and link to the appropriate page(s).
|
||||
|
||||
## Layout
|
||||
|
||||
### Overview
|
||||
This section should describe the group of settings and what they do for the device.
|
||||
|
||||
### Settings
|
||||
This section starts with an alphabetized table of settings, available values, and default values.
|
||||
|
||||
Available values should be listed with tick marks `` surrounding the value.
|
||||
|
||||
| Value Type | Example |
|
||||
| :--------: | :-----: |
|
||||
| Boolean | `true`, `false` |
|
||||
| List | `apple`, `banana`, `orange` |
|
||||
| Range | `0`-`100` |
|
||||
|
||||
After the table each setting is described in brief detail. If the available options for a setting need additional explanation, a table should be used to describe each available option.
|
||||
|
||||
### Details
|
||||
If additional details are needed, this optional section can explain that. These would include prerequisites, links to hardware guides, etc.
|
||||
|
||||
### Examples
|
||||
This optional section can have examples of configurations needed where multiple settings are required to be set up for a specific use case.
|
||||
|
||||
## Example Template
|
||||
```markdown title="Template for Settings Pages"
|
||||
---
|
||||
id: unique-id
|
||||
title: Title for Page
|
||||
sidebar_label: Label for Sidebar
|
||||
---
|
||||
<!--- Allows client-specific tabs to be used --->
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
## Overview
|
||||
|
||||
<!--- Add overview text to describe this group of settings --->
|
||||
|
||||
## Settings
|
||||
|
||||
<!--- Table of settings in alphabetical order --->
|
||||
| Setting | Acceptable Values | Default |
|
||||
| :-----: | :---------------: | :-----: |
|
||||
| my_setting_with_options | `apple`, `banana`, `orange` | `apple` |
|
||||
|
||||
<!--- H3 for each setting above (alphabetized) --->
|
||||
### my_setting_with_options
|
||||
<!--- description for what the setting does --->
|
||||
|
||||
<!--- if the setting has many options, insert a table describing what those variables do --->
|
||||
| Value | Description |
|
||||
| :---: | :---------: |
|
||||
| `apple` | Description of apple (default) |
|
||||
| `banana` | Description of banana |
|
||||
| `orange` | Description of orange |
|
||||
|
||||
<!--- Client tabs that were imported above --->
|
||||
<Tabs
|
||||
groupId="settings"
|
||||
defaultValue="cli"
|
||||
values={[
|
||||
{label: 'CLI', value: 'cli'},
|
||||
{label: 'Android', value: 'android'},
|
||||
{label: 'iOS', value: 'iOS'},
|
||||
{label: 'Web', value: 'web'},
|
||||
]}>
|
||||
<TabItem value="cli">
|
||||
CLI content here
|
||||
</TabItem>
|
||||
<TabItem value="android">
|
||||
Android content here
|
||||
</TabItem>
|
||||
<TabItem value="iOS">
|
||||
iOS content here
|
||||
</TabItem>
|
||||
<TabItem value="web">
|
||||
Web content here
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Details
|
||||
<!--- Additional details about the settings IF NEEDED otherwise delete this h2 header --->
|
||||
|
||||
## Examples
|
||||
<!--- Meant for examples where multiple settings are configured at the same time (WiFi type/SSID/password in a single command). If not needed, delete this h2 header --->
|
||||
```
|
||||
35
docs/about-documentation/vercel.md
Normal file
35
docs/about-documentation/vercel.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
id: vercel
|
||||
title: Vercel
|
||||
sidebar_label: Vercel
|
||||
---
|
||||
## Overview
|
||||
Setting up a Vercel account is an optional step that can help you view your changes to the documentation in a server environment just like the actual docs. This can be helpful to include when submitting a pull request so that developers can review your changes and visually check that things look correct.
|
||||
|
||||
## Set up Vercel account
|
||||
|
||||
- Go to [vercel.com](https://vercel.com)
|
||||
- Login with your GitHub account, click `Continue with GitHub`
|
||||
|
||||
## Link your fork of the project
|
||||
|
||||
- Click `New Project`
|
||||
- Under `Import Git Repository` select `+ Add GitHub Account`
|
||||
You'll be redirected to GitHub to allow access to select repositories.
|
||||
- Select your fork of the project: `username/Meshtastic`
|
||||
|
||||
## Configure project
|
||||
|
||||
Configure project:
|
||||
|
||||
- Set a name for the project
|
||||
- Select a framework preset: `Docusaurus 2`
|
||||
- Click `Deploy`
|
||||
|
||||
That's it! You should now see your project with a green or orange status dot showing that your fork of the project has been compiled. There will be a commit-specific url that you can share to view your changes. There also will be a branch-specific url that you can view. If there are any errors it will show up red and include the logs for you to figure out what has gone wrong.
|
||||
|
||||
:::tip
|
||||
There is a limited number of branch urls that you will be able to view. If you notice that option has disappeared, you can delete unused branches on your fork and that will enable that feature again.
|
||||
|
||||
Branch urls are helpful in PRs because they will remain constant, and you won't need to resubmit a new url for review each new commit if changes are requested.
|
||||
:::
|
||||
20
sidebars.js
20
sidebars.js
|
|
@ -196,8 +196,24 @@ module.exports = {
|
|||
Documentation: {
|
||||
"About Documentation": [
|
||||
"about-documentation/overview",
|
||||
"about-documentation/serve-docs-locally",
|
||||
]
|
||||
{
|
||||
Dependencies: [
|
||||
"about-documentation/docusaurus",
|
||||
"about-documentation/github",
|
||||
"about-documentation/vercel",
|
||||
],
|
||||
},
|
||||
{
|
||||
Examples: [
|
||||
"about-documentation/serve-docs-locally",
|
||||
],
|
||||
},
|
||||
{
|
||||
"Style Guides": [
|
||||
"about-documentation/style-guides/style-guide-settings",
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
Legal: {
|
||||
Legal: [
|
||||
|
|
|
|||
Loading…
Reference in a new issue