From 49fa994d4745edecf9d36d373f2a1e5120d8b3b3 Mon Sep 17 00:00:00 2001 From: Kevin Nguyen Date: Sun, 3 Mar 2024 12:34:43 -0700 Subject: [PATCH 1/3] Add README Versioning Move README to /docs Replace home.mdx and use README directly Update remote-content to prepend front matter to README --- .gitignore | 3 +- docs/README.md | 109 ++++++++++++++++++ docs/home.mdx | 12 -- docusaurus.config.js | 30 ++++- sidebars.js | 4 - versioned_docs/version-0.7.7/README.md | 109 ++++++++++++++++++ versioned_docs/version-0.7.7/home.mdx | 12 -- .../version-0.7.7-sidebars.json | 4 - 8 files changed, 246 insertions(+), 37 deletions(-) create mode 100644 docs/README.md delete mode 100644 docs/home.mdx create mode 100644 versioned_docs/version-0.7.7/README.md delete mode 100644 versioned_docs/version-0.7.7/home.mdx diff --git a/.gitignore b/.gitignore index 60d995c..33f9be8 100644 --- a/.gitignore +++ b/.gitignore @@ -16,5 +16,4 @@ yarn-error.log build .docusaurus -.cache-loader -README.md \ No newline at end of file +.cache-loader \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..cefaea8 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,109 @@ +--- +hide_title: true +title: "Home" +pagination_next: null +pagination_prev: null +description: "Homepage for GP2040-CE Documentation" +--- + +

+ + GP2040-CE + +

+ +

+ Multi-Platform Gamepad Firmware for RP2040 +

+ +

+ + +
+ + +

+ +

+ GP2040-CE (Community Edition) is a gamepad firmware for the Raspberry Pi Pico and other boards based on the RP2040 microcontrollers that combines multi-platform compatibility, low latency and a rich feature set to provide endless customization possibilities without sacrificing performance. +

+ +

+ GP2040-CE is compatible with PC, PS3 and PS4, Nintendo Switch, Steam Deck, MiSTer and Android. +

+ +## Links + +[Downloads](https://gp2040-ce.info/downloads/download-page) | [Installation](https://gp2040-ce.info/installation) | [Wiring](https://gp2040-ce.info/controller-build/wiring) | [Usage](https://gp2040-ce.info/usage) | [FAQ](https://gp2040-ce.info/faq/faq-general) | [GitHub](https://github.com/OpenStickCommunity/GP2040-CE) + +Full documentation can be found at [https://gp2040-ce.info](https://gp2040-ce.info) + +## Features + +- Select from 13 input modes including X-Input, Nintendo Switch, Playstation 4/5, Xbox One, D-Input, and Keyboard +- Overclocked polling rate for an average of 0.76ms of input latency in Xinput and on average 1.72 for Playstation 4/5. +- Multiple SOCD cleaning modes - Up Priority (a.k.a. Stickless), Neutral, and Second Input Priority. +- Left and Right stick emulation via D-pad inputs as well as dedicated toggle switches. +- Dual direction via D-pad + LS/RS. +- Reversed input via a button. +- [Turbo and Turbo LED](https://gp2040-ce.info/add-ons/turbo) with selectable speed +- Per-button RGB LED support. +- PWM Player indicator LED support (XInput only). +- Multiple LED profiles support. +- Support for 128x64 monochrome I2C displays - SSD1306, SH1106, and SH1107 compatible. +- Custom startup splash screen and easy image upload via web configuration. +- Support for passive buzzer speaker (3v or 5v). +- [Built-in, embedded web configuration](https://gp2040-ce.info/web-configurator) - No download required! + +Visit the [GP2040-CE Usage](https://gp2040-ce.info/usage) page for more details. + +## Performance + +Input latency is tested using the methodology outlined at [WydD's inputlag.science website](https://inputlag.science/controller/methodology), using the default 1000 Hz (1 ms) polling rate in the firmware. You can read more about the setup we use to conduct latency testing [HERE](https://github.com/OpenStickCommunity/Site/blob/main/latency_testing/README.md) if you are interested in testing for yourself or would just like to know more about the devices used to do the testing. + +| Version | Mode | Poll Rate | Min | Max | Avg | Stdev | % on time | %1f skip | %2f skip | +| ------- | ------------ | --------- | ------- | ------- | ------- | ------- | --------- | -------- | -------- | +| v0.7.7 | Xinput | 1 ms | 0.45 ms | 1.28 ms | 0.76 ms | 0.24 ms | 98.48% | 1.52% | 0% | +| v0.7.7 | Switch | 1 ms | 0.41 ms | 1.22 ms | 0.72 ms | 0.24 ms | 98.54% | 1.46% | 0% | +| v0.7.7 | Dinput (PS3) | 1 ms | 0.44 ms | 1.27 ms | 0.75 ms | 0.24 ms | 98.49% | 1.51% | 0% | +| v0.7.7 | PS4 | 1 ms | 0.55 ms | 2.17 ms | 0.86 ms | 0.24 ms | 98.30% | 1.70% | 0% | +| v0.7.7 | PS4 Hack | 1 ms | 0.55 ms | 1.38 ms | 0.86 ms | 0.24 ms | 98.32% | 1.68% | 0% | + +Full results can be found in the [GP2040-CE v0.7.7 Firmware Latency Test Results](https://github.com/OpenStickCommunity/Site/raw/main/latency_testing/GP2040-CE_Firmware_Latency_Test_Results_v0.7.7.xlsx) .xlsx Sheet. + +Results from v0.7.6 can be found [HERE](https://github.com/OpenStickCommunity/Site/raw/main/latency_testing/GP2040-CE_Firmware_Latency_Test_Results_v0.7.6.xlsx). Previous results from v0.7.5 and earlier can be found in the [GP2040-CE v0.7.5 (and before) Firmware Latency Test Results](https://github.com/OpenStickCommunity/Site/raw/main/latency_testing/GP2040-CE_Firmware_Latency_Test_Results_v0.7.5_and_before.xlsx) .xlsx Sheet. + +## Support + +If you would like to discuss features, issues or anything else related to GP2040-CE please [create an issue](https://github.com/OpenStickCommunity/GP2040-CE/issues/new) or join the [OpenStick GP2040-CE Discord](https://discord.gg/k2pxhke7q8) support channel. + +## Contributing + +Want to help improve GP2040-CE? There are a bunch of ways to contribute! + +### Community Participation + +Have an idea for a cool new feature, or just want to discuss some technical details with the developers? Join the [OpenStick GP2040-CE Discord](https://discord.gg/k2pxhke7q8) server to participate in our active and ever-growing community! + +### Pull Requests + +Pull requests are welcome and encouraged for enhancements, bug fixes and documentation updates. + +Please respect the coding style of the file(s) you are working in, and enforce the use of the `.editorconfig` file when present. + +## Acknowledgements + +- [FeralAI](https://github.com/FeralAI) for building [GP2040](https://github.com/FeralAI/GP2040) and laying the foundation for this community project +- Ha Thach's excellent [TinyUSB library](https://github.com/hathach/tinyusb) examples +- fluffymadness's [tinyusb-xinput](https://github.com/fluffymadness/tinyusb-xinput) sample +- Kevin Boone's [blog post on using RP2040 flash memory as emulated EEPROM](https://kevinboone.me/picoflash.html) +- [bitbank2](https://github.com/bitbank2) for the [OneBitDisplay](https://github.com/bitbank2/OneBitDisplay) and [BitBang_I2C](https://github.com/bitbank2/BitBang_I2C) libraries, which were ported for use with the Pico SDK +- [arntsonl](https://github.com/arntsonl) for the amazing cleanup and feature additions that brought us to v0.5.0 +- [alirin222](https://github.com/alirin222) for the awesome turbo code ([@alirin222](https://twitter.com/alirin222) on Twitter) +- [deeebug](https://github.com/deeebug) for improvements to the web-UI and fixing the PS3 home button issue +- [TheTrain](https://github.com/TheTrainGoes/GP2040-Projects) and [Fortinbra](https://github.com/Fortinbra) for helping keep our community chugging along +- [PassingLink](https://github.com/passinglink/passinglink) for the technical details and code for PS4 implementation +- [Youssef Habchi](https://youssef-habchi.com/) for allowing us to purchase a license to use Road Rage font for the project +- [tamanegitaro](https://github.com/tamanegitaro/) and [alirin222](https://github.com/alirin222) for the basis of the mini/classic controller work +- [Ryzee119](https://github.com/Ryzee119) for the wonderful [ogx360_t4](https://github.com/Ryzee119/ogx360_t4/) and xid_driver library for Original Xbox support +- [Santroller](https://github.com/Santroller/Santroller) and [GIMX](https://github.com/matlo/GIMX) for technical examples of Xbox One authentication using pass-through diff --git a/docs/home.mdx b/docs/home.mdx deleted file mode 100644 index be28e6b..0000000 --- a/docs/home.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -slug: "/" -hide_title: true -title: "Home" -pagination_next: null -pagination_prev: null -description: "Homepage for GP2040-CE" ---- - -import README from "@site/README.md"; - - diff --git a/docusaurus.config.js b/docusaurus.config.js index dba2976..916521a 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -77,11 +77,17 @@ const config = { src: "img/gp2040-ce-logo.svg", }, items: [ + { + type: "doc", + position: "left", + docId: "README", + label: "Home", + }, { type: "docSidebar", position: "left", sidebarId: "docSidebar", - label: "Home", + label: "Getting Started", }, { type: "docSidebar", @@ -137,9 +143,27 @@ const config = { name: "README", // used by CLI, must be path safe sourceBaseUrl: "https://raw.githubusercontent.com/OpenStickCommunity/GP2040-CE/main/", // the base url for the markdown (gets prepended to all of the documents when fetching) - outDir: "/", // the base directory to output to. + outDir: "/docs", // the base directory to output to. documents: ["README.md"], // the file names to download - performCleanup: true, + performCleanup: false, + modifyContent(filename, content) { + if (filename.includes("README")) { + return { + content: `--- +hide_title: true +title: "Home" +pagination_next: null +pagination_prev: null +description: "Homepage for GP2040-CE Documentation" +--- + +${content}`, // <-- this last part adds in the rest of the content, which would otherwise be discarded + }; + } + + // we don't want to modify this item, since it doesn't contain "README" in the name + return undefined; + }, }, ], [ diff --git a/sidebars.js b/sidebars.js index c4e5162..d7847ff 100644 --- a/sidebars.js +++ b/sidebars.js @@ -18,10 +18,6 @@ const sidebars = { // But you can create a sidebar manually docSidebar: [ - { - type: "doc", - id: "home", - }, { type: "category", label: "General", diff --git a/versioned_docs/version-0.7.7/README.md b/versioned_docs/version-0.7.7/README.md new file mode 100644 index 0000000..7bc9e2e --- /dev/null +++ b/versioned_docs/version-0.7.7/README.md @@ -0,0 +1,109 @@ +--- +hide_title: true +title: "Home" +pagination_next: null +pagination_prev: null +description: "Homepage for GP2040-CE Documentation" +--- + +

+ + GP2040-CE + +

+ +

+ Multi-Platform Gamepad Firmware for RP2040 +

+ +

+ + +
+ + +

+ +

+ GP2040-CE (Community Edition) is a gamepad firmware for the Raspberry Pi Pico and other boards based on the RP2040 microcontrollers that combines multi-platform compatibility, low latency and a rich feature set to provide endless customization possibilities without sacrificing performance. +

+ +

+ GP2040-CE is compatible with PC, PS3 and PS4, Nintendo Switch, Steam Deck, MiSTer and Android. +

+ +## Links + +[Downloads](https://gp2040-ce.info/downloads/download-page) | [Installation](https://gp2040-ce.info/installation) | [Wiring](https://gp2040-ce.info/controller-build/wiring) | [Usage](https://gp2040-ce.info/usage) | [FAQ](https://gp2040-ce.info/faq/faq-general) | [GitHub](https://github.com/OpenStickCommunity/GP2040-CE) + +Full documentation can be found at [https://gp2040-ce.info](https://gp2040-ce.info) + +## Features + +- Select from 13 input modes including X-Input, Nintendo Switch, Playstation 4/5, Xbox One, D-Input, and Keyboard +- Overclocked polling rate for an average of 0.76ms of input latency in Xinput and on average 1.72 for Playstation 4/5. +- Multiple SOCD cleaning modes - Up Priority (a.k.a. Stickless), Neutral, and Second Input Priority. +- Left and Right stick emulation via D-pad inputs as well as dedicated toggle switches. +- Dual direction via D-pad + LS/RS. +- Reversed input via a button. +- [Turbo and Turbo LED](https://gp2040-ce.info/add-ons/turbo) with selectable speed +- Per-button RGB LED support. +- PWM Player indicator LED support (XInput only). +- Multiple LED profiles support. +- Support for 128x64 monochrome I2C displays - SSD1306, SH1106, and SH1107 compatible. +- Custom startup splash screen and easy image upload via web configuration. +- Support for passive buzzer speaker (3v or 5v). +- [Built-in, embedded web configuration](https://gp2040-ce.info/web-configurator) - No download required! + +Visit the [GP2040-CE Usage](https://gp2040-ce.info/usage) page for more details. + +## Performance + +Input latency is tested using the methodology outlined at [WydD's inputlag.science website](https://inputlag.science/controller/methodology), using the default 1000 Hz (1 ms) polling rate in the firmware. You can read more about the setup we use to conduct latency testing [HERE](https://github.com/OpenStickCommunity/Site/blob/main/latency_testing/README.md) if you are interested in testing for yourself or would just like to know more about the devices used to do the testing. + +| Version | Mode | Poll Rate | Min | Max | Avg | Stdev | % on time | %1f skip | %2f skip | +| ------- | ------------ | --------- | ------- | ------- | ------- | ------- | --------- | -------- | -------- | +| v0.7.7 | Xinput | 1 ms | 0.45 ms | 1.28 ms | 0.76 ms | 0.24 ms | 98.48% | 1.52% | 0% | +| v0.7.7 | Switch | 1 ms | 0.41 ms | 1.22 ms | 0.72 ms | 0.24 ms | 98.54% | 1.46% | 0% | +| v0.7.7 | Dinput (PS3) | 1 ms | 0.44 ms | 1.27 ms | 0.75 ms | 0.24 ms | 98.49% | 1.51% | 0% | +| v0.7.7 | PS4 | 1 ms | 0.55 ms | 2.17 ms | 0.86 ms | 0.24 ms | 98.30% | 1.70% | 0% | +| v0.7.7 | PS4 Hack | 1 ms | 0.55 ms | 1.38 ms | 0.86 ms | 0.24 ms | 98.32% | 1.68% | 0% | + +Full results can be found in the [GP2040-CE v0.7.7 Firmware Latency Test Results](https://github.com/OpenStickCommunity/Site/raw/main/latency_testing/GP2040-CE_Firmware_Latency_Test_Results_v0.7.7.xlsx) .xlsx Sheet. + +Results from v0.7.6 can be found [HERE](https://github.com/OpenStickCommunity/Site/raw/main/latency_testing/GP2040-CE_Firmware_Latency_Test_Results_v0.7.6.xlsx). Previous results from v0.7.5 and earlier can be found in the [GP2040-CE v0.7.5 (and before) Firmware Latency Test Results](https://github.com/OpenStickCommunity/Site/raw/main/latency_testing/GP2040-CE_Firmware_Latency_Test_Results_v0.7.5_and_before.xlsx) .xlsx Sheet. + +## Support + +If you would like to discuss features, issues or anything else related to GP2040-CE please [create an issue](https://github.com/OpenStickCommunity/GP2040-CE/issues/new) or join the [OpenStick GP2040-CE Discord](https://discord.gg/k2pxhke7q8) support channel. + +## Contributing + +Want to help improve GP2040-CE? There are a bunch of ways to contribute! + +### Community Participation + +Have an idea for a cool new feature, or just want to discuss some technical details with the developers? Join the [OpenStick GP2040-CE Discord](https://discord.gg/k2pxhke7q8) server to participate in our active and ever-growing community! + +### Pull Requests + +Pull requests are welcome and encouraged for enhancements, bug fixes and documentation updates. + +Please respect the coding style of the file(s) you are working in, and enforce the use of the `.editorconfig` file when present. + +## Acknowledgements + +- [FeralAI](https://github.com/FeralAI) for building [GP2040](https://github.com/FeralAI/GP2040) and laying the foundation for this community project +- Ha Thach's excellent [TinyUSB library](https://github.com/hathach/tinyusb) examples +- fluffymadness's [tinyusb-xinput](https://github.com/fluffymadness/tinyusb-xinput) sample +- Kevin Boone's [blog post on using RP2040 flash memory as emulated EEPROM](https://kevinboone.me/picoflash.html) +- [bitbank2](https://github.com/bitbank2) for the [OneBitDisplay](https://github.com/bitbank2/OneBitDisplay) and [BitBang_I2C](https://github.com/bitbank2/BitBang_I2C) libraries, which were ported for use with the Pico SDK +- [arntsonl](https://github.com/arntsonl) for the amazing cleanup and feature additions that brought us to v0.5.0 +- [alirin222](https://github.com/alirin222) for the awesome turbo code ([@alirin222](https://twitter.com/alirin222) on Twitter) +- [deeebug](https://github.com/deeebug) for improvements to the web-UI and fixing the PS3 home button issue +- [TheTrain](https://github.com/TheTrainGoes/GP2040-Projects) and [Fortinbra](https://github.com/Fortinbra) for helping keep our community chugging along +- [PassingLink](https://github.com/passinglink/passinglink) for the technical details and code for PS4 implementation +- [Youssef Habchi](https://youssef-habchi.com/) for allowing us to purchase a license to use Road Rage font for the project +- [tamanegitaro](https://github.com/tamanegitaro/) and [alirin222](https://github.com/alirin222) for the basis of the mini/classic controller work +- [Ryzee119](https://github.com/Ryzee119) for the wonderful [ogx360_t4](https://github.com/Ryzee119/ogx360_t4/) and xid_driver library for Original Xbox support +- [Santroller](https://github.com/Santroller/Santroller) and [GIMX](https://github.com/matlo/GIMX) for technical examples of Xbox One authentication using pass-through diff --git a/versioned_docs/version-0.7.7/home.mdx b/versioned_docs/version-0.7.7/home.mdx deleted file mode 100644 index 9909c1f..0000000 --- a/versioned_docs/version-0.7.7/home.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -slug: "/" -hide_title: true -title: "Home" -pagination_next: null -pagination_prev: null -description: "Homepage for GP2040-CE" ---- - -import README from "@site/README.md"; - - diff --git a/versioned_sidebars/version-0.7.7-sidebars.json b/versioned_sidebars/version-0.7.7-sidebars.json index 98a2538..316d3e8 100644 --- a/versioned_sidebars/version-0.7.7-sidebars.json +++ b/versioned_sidebars/version-0.7.7-sidebars.json @@ -1,9 +1,5 @@ { "docSidebar": [ - { - "type": "doc", - "id": "home" - }, { "type": "category", "label": "General", From d8717f1e2d82a1d495bb944f80d79d21070b000e Mon Sep 17 00:00:00 2001 From: Kevin Nguyen Date: Sun, 3 Mar 2024 17:30:06 -0700 Subject: [PATCH 2/3] Shorten Navbar labels --- docusaurus.config.js | 4 ++-- src/css/custom.css | 4 ++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 916521a..f292c5b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -87,13 +87,13 @@ const config = { type: "docSidebar", position: "left", sidebarId: "docSidebar", - label: "Getting Started", + label: "Get Started", }, { type: "docSidebar", position: "left", sidebarId: "webConfigSidebar", - label: "Web Configurator", + label: "Web Config", }, { type: "docSidebar", diff --git a/src/css/custom.css b/src/css/custom.css index 81e1183..c3b7d91 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -54,6 +54,10 @@ img { text-align: center; } +nav.navbar { + white-space: nowrap; +} + @media only screen and (min-width: 600px) { #img-wrapper { text-align: center; From 450ffad91c441888ea7899954dda2c267b4bd743 Mon Sep 17 00:00:00 2001 From: Kevin Nguyen Date: Mon, 4 Mar 2024 01:43:09 -0700 Subject: [PATCH 3/3] Add Documentation Style Guide --- .../development/documentation-style-guide.mdx | 576 ++++++++++++++++++ docs/development/documentation-versioning.mdx | 2 +- sidebars.js | 1 + .../development/documentation-style-guide.mdx | 576 ++++++++++++++++++ .../development/documentation-versioning.mdx | 2 +- .../version-0.7.7-sidebars.json | 10 +- 6 files changed, 1158 insertions(+), 9 deletions(-) create mode 100644 docs/development/documentation-style-guide.mdx create mode 100644 versioned_docs/version-0.7.7/development/documentation-style-guide.mdx diff --git a/docs/development/documentation-style-guide.mdx b/docs/development/documentation-style-guide.mdx new file mode 100644 index 0000000..c158e1b --- /dev/null +++ b/docs/development/documentation-style-guide.mdx @@ -0,0 +1,576 @@ +--- +title: Style Guide +# tags: +# - +pagination_next: null +pagination_prev: null +toc_max_heading_level: 4 +description: "A style guide on how to write documentation for GP2040-CE using Docusaurus" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import InputLabelSelector, { + Hotkey, +} from "@site/src/components/LabelSelector.tsx"; + +# Style Guide + +GP2040-CE welcomes your contribution to our documentation. This document describes the options available for creating +content for the site. along with guidelines and conventions. + +## Markdown + +This site uses Docusaurus version 2. Docusaurus uses MDX as the parsing engine. which can parse standard Markdown syntax +as well as render React Components inside the document. + +[Docusaurus Markdown](https://docusaurus.io/docs/markdown-features) supports +[Basic Markdown Syntax](https://www.markdownguide.org/basic-syntax) and most +[Extended Syntax](https://www.markdownguide.org/extended-syntax/). You can see which features are supported +[here](https://www.markdownguide.org/tools/docusaurus/). + +## Frontmatter + +At the top of each docs page, you need to include these things: + +| Variable | Description | +| :--------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `title` | The main title of the page. This value will appear in the left hand navigation tree for the page. | +| `pagination_prev` (optional) | The ID of the documentation you want the "Previous" pagination to link to. Use null to disable showing "Previous" for this page. | +| `pagination_next` (optional) | The ID of the documentation you want the "Next" pagination to link to. Use null to disable showing "Next" for this page. | +| `toc_min_heading_level` (optional) | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. | +| `toc_max_heading_level` (optional) | The max heading level shown in the table of contents. Must be between 2 and 6. | +| `description` | This is what appears when the page is referenced in a Google search result and what appears when the page is embedded elsewhere. | +| `keywords` (optional) | A list of terms that help categorize the page for SEO purposes. | + +The fields above are sufficient for most documentation pages. However,additional frontmatter fields can be found in the +Docusaurus [plugin-content-docs documentation](https://docusaurus.io/docs/2.x/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter). + +Frontmatter will look like this at the beginning of a document: + +``` +--- +title: Documentation Style Guide +pagination_next: null +pagination_prev: null +description: "A style guide on how to write documentation for GP2040-CE using Docusaurus" +--- +``` + +## Introduction + +The first paragraph of the documentation should set the user's expectations for what they will find on the page. +Describe the key benefits to the user, but do not include links. + +## Headers + +For accessibility and SEO reasons, never have an H4 header that isn't under an H3 header, or an H3 header that isn't +under an H2 header. + +- H1 headers should never be used in a document since the title is automatically generated as an H1. +- H2 headers are used for SEO, so make sure they succinctly represent what a user will find on the page in that section. +- H3 headers are included in the page's table of contents on the right, so make sure the title describes something a + user might want to directly navigate to. +- H4 headers are to emphasize things within a subsection of the page; these can be longer than the other headers if + needed because they aren't included in the Table of Contents. + +Markdown Code: + +``` +## H2 Header + +### H3 Header + +#### H4 Header +``` + +## Content + +### Line Breaks + +All words are rendered in the same paragraph even with line breaks, so long as there isn't an empty line. +As such, it is good practice for each line to be less than 120 characters long for readability, when possible. + +If the text is contained in a Markdown table cell, `
` will need to be used. + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +This +will +all +be +on +one +line. + +The empty line above creates a new paragraph. + +This forces a soft return
+rather than creating a new paragraph + +| Column1 | Column2 | +| ------- | ------------------------------------- | +| Row 1 | - Line 1
- Line 2
- Line3 | +``` + +
+ +**Display** + + + +This +will +all +be +on +one +line. + +The empty line above creates a new paragraph. + +This forces a soft return
+rather than creating a new paragraph + +| Column1 | Column2 | +| ------- | ------------------------------------- | +| Row 1 | - Line 1
- Line 2
- Line3 | + +
+ +### Links + +#### Pages and Assets + +When linking to pages or assets, you will need to use relative links to navigate to the page and asset you need to +access. + +:::caution + +When moving files into different sub directories, make sure that you update any references to other pages/assets within +that page in addition to any other page that reference the moving page. If this is not done, this will result in broken +links and errors in the building process. + +::: + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +![GP2040-CE Placeholder Image](../assets/gp2040-ce-placeholder.png) +``` + +
+ +**Display** + + + +![GP2040-CE Placeholder Image](../assets/gp2040-ce-placeholder.png) + +
+ +If Markdown syntax is insufficient, you can use either an inline CommonJS require in JSX image tag or an ES import +syntax and JSX image tag. For more information, refer to the +[Docusaurus documentations](https://docusaurus.io/docs/2.x/markdown-features/assets#images) + +#### Components + +When linking to components, you will need to use absolute links to navigate to the page and asset you need to access. +By using `@site` from any page in any subdirectory, it will locate to the root of the repo (i.e. "/"). + +:::caution + +When moving components into different sub directories, make sure that you update any pages that utilize that component. +If this is not done, this may result in either broken pages and errors in the building process or it may simply fail to +render. + +::: + +```md +import Component from "@site/src/components/ComponentName.tsx"; +``` + +### Hotkey Combinations + +When you need to present to the user a single input or input combination, you will need to include both a label selector +at the top of the screen and use the Hotkey component to display the input or input combination. By using this component, +the user will be able to choose the relevant input mode labels to present the labels. + +To use Hotkey Combinations, you need to import two components by placing these lines below the [Frontmatter](#frontmatter), +but above the [Introduction](#introduction): + +```typescript +import InputLabelSelector, { + Hotkey, +} from "@site/src/components/LabelSelector.tsx"; +``` + +Underneath the top header for the page, include this label selector to allow users to select the input mode for Hotkey +Combination labels. + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +Select the button labels to be displayed in the usage guide: + + +
+ +Document Content +``` + +
+ +**Display** + + + +Select the button labels to be displayed in the usage guide: + + +
+ +Document Content + +
+ +### Tabs + +Tabs are a great option when an example, instructions or other text would be different in different contexts. The +primary usage of tabs on this site is to illustrate the similar content in multiple context. + +:::tip +When a page includes multiple sets of tabs, use a `groupId` so when the user selects a particular tab, +all tabs with that ID will switch to the selected tab. +::: + +To use tabs, you need to import two special methods by placing these lines below the [Frontmatter](#frontmatter), +but above the [Introduction](#introduction): + +```typescript +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +``` + +and then use the tabs as follows: + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown + + + This would include information or examples for context 1. + + + This would include information or examples for context 2. + + +``` + +
+ +**Display** + + + + + + This would include information or examples for context 1. + + + This would include information or examples for context 2. + + + +
+ +### Inline Code + +To emphasize a single class, method name, variable, direction, filename, etc. in a sentence, place single backticks +around the name. + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +This comment refers to the `GP2040-CE_X.X.X_Pico.uf2` file. +``` + +
+ +**Display** + + + +This comment refers to the `GP2040-CE_X.X.X_Pico.uf2` file. + +
+ +### Code Blocks + +The best way to display code or Markdown text to be copied is with code blocks. Markdown will highlight each language +differently, so it is helpful to specify which language you are using, and it's a good idea to include a title with the +code block as well. + + + + + + + + + + + + +
+ +**Markdown** + + + + ```md title="Example Markdown Page" + --- + title: TITLE + # tags: + # - + pagination_next: null + pagination_prev: null + description: "PAGE DESCRIPTION" + --- + + # Document Title + + CONTENT + ``` + +
+ +**Display** + + + +```md title="Example Markdown Page" +--- +title: TITLE +pagination_next: null +pagination_prev: null +description: "PAGE DESCRIPTION" +--- + +# Document Title + +CONTENT +``` + +
+ +### Admonitions + +There are four types of [Docusaurus admonitions](https://docusaurus.io/docs/markdown-features/admonitions): + +- Note - Relevant information. +- Tip - A user should do this. +- Caution - A user should pay attention to this. +- Warning - A user might do something dangerous. + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +:::note + +Relevant information for you. + +::: + +:::tip + +You should do this. + +::: + +:::caution + +You should probably pay attention to this. + +::: + +:::warning + +You are about to do something dangerous. + +::: +``` + +
+ +**Display** + + + +:::note + +Relevant information for you. + +::: + +:::tip + +You should do this. + +::: + +:::caution + +You should probably pay attention to this. + +::: + +:::warning + +You are about to do something dangerous. + +::: + +
+ +You can also change the text of an admonition by including the test next to the admonition type. + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +:::note This was labelled NOTE + +Relevant information for you. + +::: +``` + +
+ +**Display** + + + +:::note This was labelled NOTE + +Relevant information for you. + +::: + +
+ +## Adding Images to the Repo + +All image files should be included in `docs/assets` directory, in a subdirectory that corresponds to the type of content. + +| Subdirectory | Content | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `boards` | Images of RP2040 boards (commercially available or community designed) that will be referenced in `src/config/boards.tsx` to be included in Downloads page | +| `images` | General image category for documentation
- Add-ons: Start the filename with `gpc-add-ons-`
- Web Config Page: Start the filename with `gpc-`
| +| `wiring` | Images of microcontroller board pinouts to be included in `docs/controller-build/wiring.mdx` | diff --git a/docs/development/documentation-versioning.mdx b/docs/development/documentation-versioning.mdx index b828f90..cdc803d 100644 --- a/docs/development/documentation-versioning.mdx +++ b/docs/development/documentation-versioning.mdx @@ -1,5 +1,5 @@ --- -title: Documentation Versioning +title: Versioning # tags: # - pagination_next: null diff --git a/sidebars.js b/sidebars.js index d7847ff..71ce927 100644 --- a/sidebars.js +++ b/sidebars.js @@ -83,6 +83,7 @@ const sidebars = { label: "Documentation", collapsed: false, items: [ + "development/documentation-style-guide", "development/documentation-versioning", "development/documentation-preview", "development/documentation-update-downloads", diff --git a/versioned_docs/version-0.7.7/development/documentation-style-guide.mdx b/versioned_docs/version-0.7.7/development/documentation-style-guide.mdx new file mode 100644 index 0000000..c158e1b --- /dev/null +++ b/versioned_docs/version-0.7.7/development/documentation-style-guide.mdx @@ -0,0 +1,576 @@ +--- +title: Style Guide +# tags: +# - +pagination_next: null +pagination_prev: null +toc_max_heading_level: 4 +description: "A style guide on how to write documentation for GP2040-CE using Docusaurus" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import InputLabelSelector, { + Hotkey, +} from "@site/src/components/LabelSelector.tsx"; + +# Style Guide + +GP2040-CE welcomes your contribution to our documentation. This document describes the options available for creating +content for the site. along with guidelines and conventions. + +## Markdown + +This site uses Docusaurus version 2. Docusaurus uses MDX as the parsing engine. which can parse standard Markdown syntax +as well as render React Components inside the document. + +[Docusaurus Markdown](https://docusaurus.io/docs/markdown-features) supports +[Basic Markdown Syntax](https://www.markdownguide.org/basic-syntax) and most +[Extended Syntax](https://www.markdownguide.org/extended-syntax/). You can see which features are supported +[here](https://www.markdownguide.org/tools/docusaurus/). + +## Frontmatter + +At the top of each docs page, you need to include these things: + +| Variable | Description | +| :--------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `title` | The main title of the page. This value will appear in the left hand navigation tree for the page. | +| `pagination_prev` (optional) | The ID of the documentation you want the "Previous" pagination to link to. Use null to disable showing "Previous" for this page. | +| `pagination_next` (optional) | The ID of the documentation you want the "Next" pagination to link to. Use null to disable showing "Next" for this page. | +| `toc_min_heading_level` (optional) | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. | +| `toc_max_heading_level` (optional) | The max heading level shown in the table of contents. Must be between 2 and 6. | +| `description` | This is what appears when the page is referenced in a Google search result and what appears when the page is embedded elsewhere. | +| `keywords` (optional) | A list of terms that help categorize the page for SEO purposes. | + +The fields above are sufficient for most documentation pages. However,additional frontmatter fields can be found in the +Docusaurus [plugin-content-docs documentation](https://docusaurus.io/docs/2.x/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter). + +Frontmatter will look like this at the beginning of a document: + +``` +--- +title: Documentation Style Guide +pagination_next: null +pagination_prev: null +description: "A style guide on how to write documentation for GP2040-CE using Docusaurus" +--- +``` + +## Introduction + +The first paragraph of the documentation should set the user's expectations for what they will find on the page. +Describe the key benefits to the user, but do not include links. + +## Headers + +For accessibility and SEO reasons, never have an H4 header that isn't under an H3 header, or an H3 header that isn't +under an H2 header. + +- H1 headers should never be used in a document since the title is automatically generated as an H1. +- H2 headers are used for SEO, so make sure they succinctly represent what a user will find on the page in that section. +- H3 headers are included in the page's table of contents on the right, so make sure the title describes something a + user might want to directly navigate to. +- H4 headers are to emphasize things within a subsection of the page; these can be longer than the other headers if + needed because they aren't included in the Table of Contents. + +Markdown Code: + +``` +## H2 Header + +### H3 Header + +#### H4 Header +``` + +## Content + +### Line Breaks + +All words are rendered in the same paragraph even with line breaks, so long as there isn't an empty line. +As such, it is good practice for each line to be less than 120 characters long for readability, when possible. + +If the text is contained in a Markdown table cell, `
` will need to be used. + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +This +will +all +be +on +one +line. + +The empty line above creates a new paragraph. + +This forces a soft return
+rather than creating a new paragraph + +| Column1 | Column2 | +| ------- | ------------------------------------- | +| Row 1 | - Line 1
- Line 2
- Line3 | +``` + +
+ +**Display** + + + +This +will +all +be +on +one +line. + +The empty line above creates a new paragraph. + +This forces a soft return
+rather than creating a new paragraph + +| Column1 | Column2 | +| ------- | ------------------------------------- | +| Row 1 | - Line 1
- Line 2
- Line3 | + +
+ +### Links + +#### Pages and Assets + +When linking to pages or assets, you will need to use relative links to navigate to the page and asset you need to +access. + +:::caution + +When moving files into different sub directories, make sure that you update any references to other pages/assets within +that page in addition to any other page that reference the moving page. If this is not done, this will result in broken +links and errors in the building process. + +::: + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +![GP2040-CE Placeholder Image](../assets/gp2040-ce-placeholder.png) +``` + +
+ +**Display** + + + +![GP2040-CE Placeholder Image](../assets/gp2040-ce-placeholder.png) + +
+ +If Markdown syntax is insufficient, you can use either an inline CommonJS require in JSX image tag or an ES import +syntax and JSX image tag. For more information, refer to the +[Docusaurus documentations](https://docusaurus.io/docs/2.x/markdown-features/assets#images) + +#### Components + +When linking to components, you will need to use absolute links to navigate to the page and asset you need to access. +By using `@site` from any page in any subdirectory, it will locate to the root of the repo (i.e. "/"). + +:::caution + +When moving components into different sub directories, make sure that you update any pages that utilize that component. +If this is not done, this may result in either broken pages and errors in the building process or it may simply fail to +render. + +::: + +```md +import Component from "@site/src/components/ComponentName.tsx"; +``` + +### Hotkey Combinations + +When you need to present to the user a single input or input combination, you will need to include both a label selector +at the top of the screen and use the Hotkey component to display the input or input combination. By using this component, +the user will be able to choose the relevant input mode labels to present the labels. + +To use Hotkey Combinations, you need to import two components by placing these lines below the [Frontmatter](#frontmatter), +but above the [Introduction](#introduction): + +```typescript +import InputLabelSelector, { + Hotkey, +} from "@site/src/components/LabelSelector.tsx"; +``` + +Underneath the top header for the page, include this label selector to allow users to select the input mode for Hotkey +Combination labels. + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +Select the button labels to be displayed in the usage guide: + + +
+ +Document Content +``` + +
+ +**Display** + + + +Select the button labels to be displayed in the usage guide: + + +
+ +Document Content + +
+ +### Tabs + +Tabs are a great option when an example, instructions or other text would be different in different contexts. The +primary usage of tabs on this site is to illustrate the similar content in multiple context. + +:::tip +When a page includes multiple sets of tabs, use a `groupId` so when the user selects a particular tab, +all tabs with that ID will switch to the selected tab. +::: + +To use tabs, you need to import two special methods by placing these lines below the [Frontmatter](#frontmatter), +but above the [Introduction](#introduction): + +```typescript +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +``` + +and then use the tabs as follows: + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown + + + This would include information or examples for context 1. + + + This would include information or examples for context 2. + + +``` + +
+ +**Display** + + + + + + This would include information or examples for context 1. + + + This would include information or examples for context 2. + + + +
+ +### Inline Code + +To emphasize a single class, method name, variable, direction, filename, etc. in a sentence, place single backticks +around the name. + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +This comment refers to the `GP2040-CE_X.X.X_Pico.uf2` file. +``` + +
+ +**Display** + + + +This comment refers to the `GP2040-CE_X.X.X_Pico.uf2` file. + +
+ +### Code Blocks + +The best way to display code or Markdown text to be copied is with code blocks. Markdown will highlight each language +differently, so it is helpful to specify which language you are using, and it's a good idea to include a title with the +code block as well. + + + + + + + + + + + + +
+ +**Markdown** + + + + ```md title="Example Markdown Page" + --- + title: TITLE + # tags: + # - + pagination_next: null + pagination_prev: null + description: "PAGE DESCRIPTION" + --- + + # Document Title + + CONTENT + ``` + +
+ +**Display** + + + +```md title="Example Markdown Page" +--- +title: TITLE +pagination_next: null +pagination_prev: null +description: "PAGE DESCRIPTION" +--- + +# Document Title + +CONTENT +``` + +
+ +### Admonitions + +There are four types of [Docusaurus admonitions](https://docusaurus.io/docs/markdown-features/admonitions): + +- Note - Relevant information. +- Tip - A user should do this. +- Caution - A user should pay attention to this. +- Warning - A user might do something dangerous. + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +:::note + +Relevant information for you. + +::: + +:::tip + +You should do this. + +::: + +:::caution + +You should probably pay attention to this. + +::: + +:::warning + +You are about to do something dangerous. + +::: +``` + +
+ +**Display** + + + +:::note + +Relevant information for you. + +::: + +:::tip + +You should do this. + +::: + +:::caution + +You should probably pay attention to this. + +::: + +:::warning + +You are about to do something dangerous. + +::: + +
+ +You can also change the text of an admonition by including the test next to the admonition type. + + + + + + + + + + + + +
+ +**Markdown** + + + +```markdown +:::note This was labelled NOTE + +Relevant information for you. + +::: +``` + +
+ +**Display** + + + +:::note This was labelled NOTE + +Relevant information for you. + +::: + +
+ +## Adding Images to the Repo + +All image files should be included in `docs/assets` directory, in a subdirectory that corresponds to the type of content. + +| Subdirectory | Content | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `boards` | Images of RP2040 boards (commercially available or community designed) that will be referenced in `src/config/boards.tsx` to be included in Downloads page | +| `images` | General image category for documentation
- Add-ons: Start the filename with `gpc-add-ons-`
- Web Config Page: Start the filename with `gpc-`
| +| `wiring` | Images of microcontroller board pinouts to be included in `docs/controller-build/wiring.mdx` | diff --git a/versioned_docs/version-0.7.7/development/documentation-versioning.mdx b/versioned_docs/version-0.7.7/development/documentation-versioning.mdx index bb35d16..7863544 100644 --- a/versioned_docs/version-0.7.7/development/documentation-versioning.mdx +++ b/versioned_docs/version-0.7.7/development/documentation-versioning.mdx @@ -1,5 +1,5 @@ --- -title: Documentation Versioning +title: Versioning # tags: # - pagination_next: null diff --git a/versioned_sidebars/version-0.7.7-sidebars.json b/versioned_sidebars/version-0.7.7-sidebars.json index 316d3e8..7feeec4 100644 --- a/versioned_sidebars/version-0.7.7-sidebars.json +++ b/versioned_sidebars/version-0.7.7-sidebars.json @@ -32,10 +32,7 @@ "type": "category", "label": "Controller Building", "collapsed": false, - "items": [ - "controller-build/wiring", - "controller-build/usb-host" - ] + "items": ["controller-build/wiring", "controller-build/usb-host"] } ], "webConfigSidebar": [ @@ -69,15 +66,14 @@ "type": "category", "label": "Firmware", "collapsed": false, - "items": [ - "development/firmware-development" - ] + "items": ["development/firmware-development"] }, { "type": "category", "label": "Documentation", "collapsed": false, "items": [ + "development/documentation-style-guide", "development/documentation-versioning", "development/documentation-preview", "development/documentation-update-downloads"