From 5656dc6a778aee9049f0c60787e5e6e9e9e1a56c Mon Sep 17 00:00:00 2001 From: David Ansermino <14164624+ansermino@users.noreply.github.com> Date: Thu, 19 Dec 2024 13:08:56 -0500 Subject: [PATCH 1/5] Update docs readme --- docs/README.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/README.md b/docs/README.md index 9b02c672ab4..01cc185282c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,32 +2,36 @@ This directory contains a Docusaurus documentation website for both user and developer documentation. +## Getting Started + +> Note: This project uses [Yarn](https://yarnpkg.com/getting-started/install) + ### Installation +Install the required dependencies: ``` $ yarn ``` ### Local Development - +Start local development server: ``` $ yarn start ``` -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. - -### Spellcheck +### CI Checks +These commands are recommended to run before commiting code. They run as checks in CI. ``` -yarn spellcheck +yarn spellcheck # Checks spelling +yarn format # Run prettier to fix formatting issues +yarn typecheck # Validate typescript files ``` - -You can add unknown words to `dictionary.txt`. +> **How to Fix Spellcheck Errors:** You can add unknown words to `dictionary.txt`. ### Build - +To compile an optimized production build: ``` $ yarn build ``` -This command generates static content into the `build` directory and can be served using any static contents hosting service. From 92f35e58af133936fe2e5532b98c95fe2b6cf6ce Mon Sep 17 00:00:00 2001 From: David Ansermino <14164624+ansermino@users.noreply.github.com> Date: Thu, 19 Dec 2024 13:28:17 -0500 Subject: [PATCH 2/5] Remove refs to old docs url --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b95617ff71f..85642398216 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,7 +37,7 @@ forward to your contributions. 🎉 ## I Have a Question > If you want to ask a question, we assume that you have read the available -> [Documentation](https://forest-docs-v2.pages.dev/). +> [Documentation](https://docs.forest.chainsafe.io/). Before you ask a question, it is best to search for existing [Issues](https://github.com/ChainSafe/forest/issues) or @@ -82,7 +82,7 @@ steps in advance to help us fix any potential bug as fast as possible. - Make sure that you are using the latest version. - Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (Make sure that you have read the - [documentation](https://forest-docs-v2.pages.dev/). If you are looking for + [documentation](https://docs.forest.chainsafe.io/). If you are looking for support, you might want to check [this section](#i-have-a-question)). - To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing @@ -143,7 +143,7 @@ community to understand your suggestion and find related suggestions. #### 🎯 Before Submitting an Enhancement - Make sure that you are using the latest version. -- Read the [documentation](https://forest-docs-v2.pages.dev/) carefully and find +- Read the [documentation](https://docs.forest.chainsafe.io/) carefully and find out if the functionality is already covered, maybe by an individual configuration. - Perform a [search](https://github.com/ChainSafe/forest/issues) to see if the @@ -225,7 +225,7 @@ eternally grateful and hope you will continue to contribute to the project. ### 📚 Improving The Documentation The documentation is currently hosted on -[forest-docs-v2.pages.dev](https://forest-docs-v2.pages.dev/). If you find any +[docs.forest.chainsafe.io](https://docs.forest.chainsafe.io/). If you find any issues with the documentation, please create an issue as the repository is not public yet. From df20b7942185b7fd48fbe401988271720a324916 Mon Sep 17 00:00:00 2001 From: David Ansermino <14164624+ansermino@users.noreply.github.com> Date: Thu, 19 Dec 2024 13:48:35 -0500 Subject: [PATCH 3/5] Expand readme --- docs/README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/README.md b/docs/README.md index 01cc185282c..18d7b20e974 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,6 +2,25 @@ This directory contains a Docusaurus documentation website for both user and developer documentation. +## Overview +The site it comprised of two sub-sites - user documentation (`/`) and developer documentation (`/developers`). There is intentionally no link from the user docs to the developer docs, to avoid overwhelming users with unnecessary info. + +### User Docs + +Available at the root (`/`), default location for anyone visiting the documentation domain. + +Follows the [Diátaxis](https://diataxis.fr/) framework for structuring documentation. The site is divided into four types of documentation: tutorials (Getting Started), how-to guides (Guides), explanations (Knowledge Base) and reference (Reference). + +#### CLI Docs +These docs are automatically generated from the Forest CLI. See [script](/docs/docs/users/reference/cli.sh). + +#### JSON-RPC Docs +We use the OpenRPC document from Forest to populate the documentation for each method. For this we use `@metamask/docusaurus-openrpc`. + +### Developer Docs + +Available at `/developers`. Comprised of a collection of documents aimed at contributors. May be relevant to power users. + ## Getting Started > Note: This project uses [Yarn](https://yarnpkg.com/getting-started/install) @@ -35,3 +54,6 @@ To compile an optimized production build: $ yarn build ``` +## Deployment + +The documentation site is continuously deployed to CloudFlare Pages, triggered on every commit to `main`. [This workflow](/.github/workflows/docs-deploy.yml) defines the deployment process. \ No newline at end of file From 3123e89a06c622375e841e23b12576ea3db6295f Mon Sep 17 00:00:00 2001 From: David Ansermino <14164624+ansermino@users.noreply.github.com> Date: Tue, 7 Jan 2025 12:15:21 -0500 Subject: [PATCH 4/5] Refine readme --- docs/README.md | 71 +++++++++++++++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 27 deletions(-) diff --git a/docs/README.md b/docs/README.md index 18d7b20e974..eaca68d3f11 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,25 +2,6 @@ This directory contains a Docusaurus documentation website for both user and developer documentation. -## Overview -The site it comprised of two sub-sites - user documentation (`/`) and developer documentation (`/developers`). There is intentionally no link from the user docs to the developer docs, to avoid overwhelming users with unnecessary info. - -### User Docs - -Available at the root (`/`), default location for anyone visiting the documentation domain. - -Follows the [Diátaxis](https://diataxis.fr/) framework for structuring documentation. The site is divided into four types of documentation: tutorials (Getting Started), how-to guides (Guides), explanations (Knowledge Base) and reference (Reference). - -#### CLI Docs -These docs are automatically generated from the Forest CLI. See [script](/docs/docs/users/reference/cli.sh). - -#### JSON-RPC Docs -We use the OpenRPC document from Forest to populate the documentation for each method. For this we use `@metamask/docusaurus-openrpc`. - -### Developer Docs - -Available at `/developers`. Comprised of a collection of documents aimed at contributors. May be relevant to power users. - ## Getting Started > Note: This project uses [Yarn](https://yarnpkg.com/getting-started/install) @@ -38,9 +19,15 @@ Start local development server: $ yarn start ``` +### Build +To compile an optimized production build: +``` +$ yarn build +``` + ### CI Checks -These commands are recommended to run before commiting code. They run as checks in CI. +These commands are recommended to run before commiting code. They are run as checks in CI. ``` yarn spellcheck # Checks spelling yarn format # Run prettier to fix formatting issues @@ -48,12 +35,42 @@ yarn typecheck # Validate typescript files ``` > **How to Fix Spellcheck Errors:** You can add unknown words to `dictionary.txt`. -### Build -To compile an optimized production build: -``` -$ yarn build -``` +### Deployment + +The documentation site is continuously deployed to CloudFlare Pages, triggered on every commit to `main`. [This workflow](/.github/workflows/docs-deploy.yml) defines the deployment process. + + +## Site Structure +The site it comprised of two sub-sites - user documentation (`/`) and developer documentation (`/developers`). There is intentionally no link from the user docs to the developer docs, to avoid overwhelming users with unnecessary info. + +### User Docs + +Available at the root (`/`), default location for anyone visiting the documentation domain. Source files are under `docs/user` + +Follows the [Diátaxis](https://diataxis.fr/) framework for structuring documentation. The site is divided into four types of documentation: tutorials (Getting Started), how-to guides (Guides), explanations (Knowledge Base) and reference (Reference). + +#### CLI Docs +These docs are automatically generated from the Forest CLI. See [script](/docs/docs/users/reference/cli.sh). + +#### JSON-RPC Docs +We use the OpenRPC document from Forest to populate the documentation for each method. For this we use `@metamask/docusaurus-openrpc`. + +### Developer Docs + +Available at `/developers`, source code is located in `docs/developers`. Comprised of a collection of documents aimed at contributors. May be relevant to power users. + +> Note: As a general rule of thumb, if it involes reading or writing Rust, it should live under the Developer documentation. + +## Contributing + +### References +- [Docusaurus Guide](https://docusaurus.io/docs/category/guides) +- [Docusaurus Configuration Docs](https://docusaurus.io/docs/api/docusaurus-config) +- [Forest Contributor Guidelines](../CONTRIBUTING.md) -## Deployment +### Useful Features -The documentation site is continuously deployed to CloudFlare Pages, triggered on every commit to `main`. [This workflow](/.github/workflows/docs-deploy.yml) defines the deployment process. \ No newline at end of file +- Admonitions (eg. Info, Warning, etc): https://docusaurus.io/docs/markdown-features/admonitions +- Mermaid Diagrams: https://docusaurus.io/docs/markdown-features/diagrams +- MDX (embedding JavaScript): https://docusaurus.io/docs/markdown-features/react +- Code Blocks: https://docusaurus.io/docs/markdown-features/code-blocks \ No newline at end of file From 4da3f1a369fc70f6b2f5b3ba9bb721eb45d0bf2a Mon Sep 17 00:00:00 2001 From: David Ansermino <14164624+ansermino@users.noreply.github.com> Date: Tue, 7 Jan 2025 12:32:45 -0500 Subject: [PATCH 5/5] Obey the linter masters --- docs/README.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index eaca68d3f11..7721beaf9cd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,18 +9,23 @@ This directory contains a Docusaurus documentation website for both user and dev ### Installation Install the required dependencies: + ``` $ yarn ``` ### Local Development + Start local development server: + ``` $ yarn start ``` ### Build + To compile an optimized production build: + ``` $ yarn build ``` @@ -28,19 +33,21 @@ $ yarn build ### CI Checks These commands are recommended to run before commiting code. They are run as checks in CI. + ``` yarn spellcheck # Checks spelling yarn format # Run prettier to fix formatting issues yarn typecheck # Validate typescript files ``` + > **How to Fix Spellcheck Errors:** You can add unknown words to `dictionary.txt`. ### Deployment -The documentation site is continuously deployed to CloudFlare Pages, triggered on every commit to `main`. [This workflow](/.github/workflows/docs-deploy.yml) defines the deployment process. - +The documentation site is continuously deployed to CloudFlare Pages, triggered on every commit to `main`. [This workflow](/.github/workflows/docs-deploy.yml) defines the deployment process. ## Site Structure + The site it comprised of two sub-sites - user documentation (`/`) and developer documentation (`/developers`). There is intentionally no link from the user docs to the developer docs, to avoid overwhelming users with unnecessary info. ### User Docs @@ -50,9 +57,11 @@ Available at the root (`/`), default location for anyone visiting the documentat Follows the [Diátaxis](https://diataxis.fr/) framework for structuring documentation. The site is divided into four types of documentation: tutorials (Getting Started), how-to guides (Guides), explanations (Knowledge Base) and reference (Reference). #### CLI Docs + These docs are automatically generated from the Forest CLI. See [script](/docs/docs/users/reference/cli.sh). #### JSON-RPC Docs + We use the OpenRPC document from Forest to populate the documentation for each method. For this we use `@metamask/docusaurus-openrpc`. ### Developer Docs @@ -64,6 +73,7 @@ Available at `/developers`, source code is located in `docs/developers`. Compris ## Contributing ### References + - [Docusaurus Guide](https://docusaurus.io/docs/category/guides) - [Docusaurus Configuration Docs](https://docusaurus.io/docs/api/docusaurus-config) - [Forest Contributor Guidelines](../CONTRIBUTING.md) @@ -73,4 +83,4 @@ Available at `/developers`, source code is located in `docs/developers`. Compris - Admonitions (eg. Info, Warning, etc): https://docusaurus.io/docs/markdown-features/admonitions - Mermaid Diagrams: https://docusaurus.io/docs/markdown-features/diagrams - MDX (embedding JavaScript): https://docusaurus.io/docs/markdown-features/react -- Code Blocks: https://docusaurus.io/docs/markdown-features/code-blocks \ No newline at end of file +- Code Blocks: https://docusaurus.io/docs/markdown-features/code-blocks