From 9ccb340d63379413a2bae640b9334be6687e5f59 Mon Sep 17 00:00:00 2001 From: nirname Date: Fri, 5 Jan 2024 13:56:36 +0000 Subject: [PATCH] Update docs --- docs/community/setup.md | 115 ---------------- docs/community/workflow.md | 128 ------------------ docs/config/usage.md | 2 +- docs/contributing/contributing.md | 2 +- docs/contributing/setup.md | 115 ---------------- docs/contributing/workflow.md | 128 ------------------ .../img/python-mermaid-integration.png | Bin 7 files changed, 2 insertions(+), 488 deletions(-) delete mode 100644 docs/community/setup.md delete mode 100644 docs/community/workflow.md delete mode 100644 docs/contributing/setup.md delete mode 100644 docs/contributing/workflow.md rename docs/{config => ecosystem}/img/python-mermaid-integration.png (100%) diff --git a/docs/community/setup.md b/docs/community/setup.md deleted file mode 100644 index 33c13519d..000000000 --- a/docs/community/setup.md +++ /dev/null @@ -1,115 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/setup.md](../../packages/mermaid/src/docs/community/setup.md). - -# Initial Setup - -Initial setup consists of 3 main steps: - -```mermaid -flowchart LR - source --> requirements --> setup - - source[Get the source code] - requirements[Install the requirements] - setup[Install packages] -``` - -## Get the Source Code - -In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. - -Then you **clone** a copy to your local development machine (e.g. where you code) to make a copy with all the files to work with. - -[Fork mermaid](https://github.com/mermaid-js/mermaid/fork) to start contributing to the main project and its documentation, or [search for other repositories](https://github.com/orgs/mermaid-js/repositories). - -[Here is a GitHub document that gives an overview of the process](https://docs.github.com/en/get-started/quickstart/fork-a-repo). - -```bash -git clone git@github.com/your-fork/mermaid -``` - -Once you have cloned the repository onto your development machine, change into the `mermaid` project folder (the top level directory of the mermaid project repository) - -```bash -cd mermaid -``` - -## Install Requirements - -We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. - -### Host - -These are the tools we use for working with the code and documentation: - -- [volta](https://volta.sh/) to manage node versions. -- [Node.js](https://nodejs.org/en/). `volta install node` -- [pnpm](https://pnpm.io/) package manager. `volta install pnpm` -- [npx](https://docs.npmjs.com/cli/v8/commands/npx) the packaged executor in npm. This is needed [to install pnpm.](#install-packages) - -### Docker - -[Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. - -Optionally, to run GUI (Cypress) within Docker you will also need an X11 server installed. -You might already have it installed, so check this by running: - -```bash -echo $DISPLAY -``` - -If the `$DISPLAY` variable is not empty, then an X11 server is running. Otherwise you may need to install one. - -## Install packages - -### Host - -Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't support it yet. - -```bash -npx pnpm install # npx is required for first install -``` - -### Docker - -For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands. - -Make sure that `./run` script is executable: - -```bash -chmod +x run -``` - -> **💡 Tip** -> To get detailed help simply type `./run` or `./run help`. -> -> It also has short _Development quick start guide_ embedded. - -```bash -./run pnpm install # Install packages -``` - -## Verify Everything Works - -This step is optional, but it helps to make sure that everything in development branch was OK before you started making any changes. - -You can run the `test` script to verify that pnpm is working _and_ that the repository has been cloned correctly: - -**Host** - -```bash -pnpm test -``` - -**Docker** - -```bash -./run pnpm test -``` - -The `test` script and others are in the top-level `package.json` file. - -All tests should run successfully without any errors or failures. (You might see _lint_ or _formatting_ warnings; those are ok during this step.) diff --git a/docs/community/workflow.md b/docs/community/workflow.md deleted file mode 100644 index 2ccc36e05..000000000 --- a/docs/community/workflow.md +++ /dev/null @@ -1,128 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/workflow.md](../../packages/mermaid/src/docs/community/workflow.md). - -# Workflow - -Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. - -Development is done in the `develop` branch. - -Once development is done we create a `release/vX.X.X` branch from `develop` for testing. - -Once the release happens we add a tag to the `release` branch and merge it with `master`. The live product and on-line documentation are what is in the `master` branch. - -```mermaid - flowchart TB - - branch --> update --> submit --> review --> branch - branch[Checkout a new branch] - update[Make changes] - submit[Submit a PR] - review[Review and merge] -``` - -## Checkout a New Branch - -> **💡 Tip** -> All new work should be based on the `develop` branch. - -Make sure you have the most up-to-date version of the `develop` branch. - -Check out the `develop` branch, then `fetch` or `pull` to update it: - -```bash -git checkout develop -git fetch # or `git pull` -``` - -Create a new branch for your work: - -```bash -git checkout -b docs/2910_update-contributing-guidelines -``` - -We use the following naming convention for branches: - -```txt -[feature | bug | chore | docs]/[issue number]_[short-description] -``` - -You can always check current [configuration of labelling and branch prefixes](https://github.com/mermaid-js/mermaid/blob/develop/.github/pr-labeler.yml) - -- The first part is the **type** of change: a `feature`, `bug`, `chore`, `docs` -- followed by a **slash** (`/`),which helps to group like types together in many git tools -- followed by the **issue number**, e.g. `2910` -- followed by an **underscore** (`_`) -- followed by a **short description** with dashes (`-`) or underscores (`_`) instead of spaces - -```mermaid -flowchart LR - feature --> slash - bug --> slash - chore --> slash - docs --> slash - slash --> 2945 --> underscore - slash --> 1123 --> underscore - underscore --> short_description_1 - underscore --> short_description_2 - - underscore["_"] - slash["/"] - - short_description_1["state-diagram-new-arrow-florbs"] - short_description_2["fix_random_ugly_red_text"] -``` - -If your work is specific to a single diagram type, it is a good idea to put the diagram type at the start of the description. This will help us keep release notes organized by a diagram type. - -> **Note** -> A new feature described in issue 2945 that adds a new arrow type called 'florbs' to state diagrams -> -> `feature/2945_state-diagram-new-arrow-florbs` - -> **💡 Tip** -> A bug described in issue 1123 that causes random ugly red text in multiple diagram types -> -> `bug/1123_fix_random_ugly_red_text` - -## Make changes - -Source code and the documentation are located \[`packages/mermaid`]\(() folder. -You may need to update both, depending on your task. - -Read our guides on [how to contribute to code](./code.md) and [how to contribute to documentation](./documentation.md). - -## Submit your pull request - -> **Note** -> Do not forget to push your changes -> -> ```bash -> git push -u origin docs/2910_update-contributing-guidelines -> ``` - -We make all changes via Pull Requests (PRs). Open a new one. - -Right now we are not following any strict rules about naming PRs. Give it a representative title and short description. There is also a [pull_request_template](https://github.com/mermaid-js/mermaid/blob/develop/.github/pull_request_template.md) which will help you with it. - -In case in its description contains a [magic comment](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) your PR will be automatically attached to the issue: - -```markdown -Resolves # -``` - -You can edit it if needed. - -## Congratulations - -You have successfully submitted your improvements! What is next? - -- PRs will be reviewed by active maintainers, who will provide feedback and request changes as needed. -- The maintainers will request a review from _knsv_, if necessary. -- Once the PR is approved, the maintainers will merge the PR into the `develop` branch. -- When a release is ready, the `release/x.x.x` branch will be created, extensively tested and knsv will be in charge of the release process. - -_knsv, Knut Sveidqvist_ is in charge of the final release process and the active maintainers are in charge of reviewing and merging most PRs. diff --git a/docs/config/usage.md b/docs/config/usage.md index 8bd34345f..7c3bc2675 100644 --- a/docs/config/usage.md +++ b/docs/config/usage.md @@ -20,7 +20,7 @@ Please note that you can switch versions through the dropdown box at the top rig For the majority of users, Using the [Live Editor](https://mermaid.live/) would be sufficient, however you may also opt to deploy mermaid as a dependency or using the [Mermaid API](./setup/README.md). -We have compiled some Video [Tutorials](./Tutorials.md) on how to use the Mermaid Live Editor. +We have compiled some Video [Tutorials](../comminuty/tutorials.md) on how to use the Mermaid Live Editor. ### Installing and Hosting Mermaid on a Webpage diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index f63f71f5f..90048ba03 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -355,7 +355,7 @@ it('should render forks and joins', () => { ### Update Documentation > **💡 Tip** -> Our documentation is managed in `packages/mermaid/src/docs`. Details on how to edit is in the [documentation section](#documentation) +> Our documentation is managed in `packages/mermaid/src/docs`. Details on how to edit is in the [documentation section](documentation) If the users have no way to know that things have changed, then you haven't really _fixed_ anything for the users; you've just added to making Mermaid feel broken. Likewise, if users don't know that there is a new feature that you've implemented, it will forever remain unknown and unused. diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md deleted file mode 100644 index 952eb8b69..000000000 --- a/docs/contributing/setup.md +++ /dev/null @@ -1,115 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/setup.md](../../packages/mermaid/src/docs/contributing/setup.md). - -# Initial Setup - -Initial setup consists of 3 main steps: - -```mermaid -flowchart LR - source --> requirements --> setup - - source[Get the source code] - requirements[Install the requirements] - setup[Install packages] -``` - -## Get the Source Code - -In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. - -Then you **clone** a copy to your local development machine (e.g. where you code) to make a copy with all the files to work with. - -[Fork mermaid](https://github.com/mermaid-js/mermaid/fork) to start contributing to the main project and its documentation, or [search for other repositories](https://github.com/orgs/mermaid-js/repositories). - -[Here is a GitHub document that gives an overview of the process](https://docs.github.com/en/get-started/quickstart/fork-a-repo). - -```bash -git clone git@github.com/your-fork/mermaid -``` - -Once you have cloned the repository onto your development machine, change into the `mermaid` project folder (the top level directory of the mermaid project repository) - -```bash -cd mermaid -``` - -## Install Requirements - -We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences. - -### Host - -These are the tools we use for working with the code and documentation: - -- [volta](https://volta.sh/) to manage node versions. -- [Node.js](https://nodejs.org/en/). `volta install node` -- [pnpm](https://pnpm.io/) package manager. `volta install pnpm` -- [npx](https://docs.npmjs.com/cli/v8/commands/npx) the packaged executor in npm. This is needed [to install pnpm.](#install-packages) - -### Docker - -[Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. - -Optionally, to run GUI (Cypress) within Docker you will also need an X11 server installed. -You might already have it installed, so check this by running: - -```bash -echo $DISPLAY -``` - -If the `$DISPLAY` variable is not empty, then an X11 server is running. Otherwise you may need to install one. - -## Install packages - -### Host - -Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't support it yet. - -```bash -npx pnpm install # npx is required for first install -``` - -### Docker - -For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands. - -Make sure that `./run` script is executable: - -```bash -chmod +x run -``` - -> **💡 Tip** -> To get detailed help simply type `./run` or `./run help`. -> -> It also has short _Development quick start guide_ embedded. - -```bash -./run pnpm install # Install packages -``` - -## Verify Everything Works - -This step is optional, but it helps to make sure that everything in development branch was OK before you started making any changes. - -You can run the `test` script to verify that pnpm is working _and_ that the repository has been cloned correctly: - -**Host** - -```bash -pnpm test -``` - -**Docker** - -```bash -./run pnpm test -``` - -The `test` script and others are in the top-level `package.json` file. - -All tests should run successfully without any errors or failures. (You might see _lint_ or _formatting_ warnings; those are ok during this step.) diff --git a/docs/contributing/workflow.md b/docs/contributing/workflow.md deleted file mode 100644 index f31cc8afa..000000000 --- a/docs/contributing/workflow.md +++ /dev/null @@ -1,128 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/contributing/workflow.md](../../packages/mermaid/src/docs/contributing/workflow.md). - -# Workflow - -Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching. - -Development is done in the `develop` branch. - -Once development is done we create a `release/vX.X.X` branch from `develop` for testing. - -Once the release happens we add a tag to the `release` branch and merge it with `master`. The live product and on-line documentation are what is in the `master` branch. - -```mermaid - flowchart TB - - branch --> update --> submit --> review --> branch - branch[Checkout a new branch] - update[Make changes] - submit[Submit a PR] - review[Review and merge] -``` - -## Checkout a New Branch - -> **💡 Tip** -> All new work should be based on the `develop` branch. - -Make sure you have the most up-to-date version of the `develop` branch. - -Check out the `develop` branch, then `fetch` or `pull` to update it: - -```bash -git checkout develop -git fetch # or `git pull` -``` - -Create a new branch for your work: - -```bash -git checkout -b docs/2910_update-contributing-guidelines -``` - -We use the following naming convention for branches: - -```txt -[feature | bug | chore | docs]/[issue number]_[short-description] -``` - -You can always check current [configuration of labelling and branch prefixes](https://github.com/mermaid-js/mermaid/blob/develop/.github/pr-labeler.yml) - -- The first part is the **type** of change: a `feature`, `bug`, `chore`, `docs` -- followed by a **slash** (`/`),which helps to group like types together in many git tools -- followed by the **issue number**, e.g. `2910` -- followed by an **underscore** (`_`) -- followed by a **short description** with dashes (`-`) or underscores (`_`) instead of spaces - -```mermaid -flowchart LR - feature --> slash - bug --> slash - chore --> slash - docs --> slash - slash --> 2945 --> underscore - slash --> 1123 --> underscore - underscore --> short_description_1 - underscore --> short_description_2 - - underscore["_"] - slash["/"] - - short_description_1["state-diagram-new-arrow-florbs"] - short_description_2["fix_random_ugly_red_text"] -``` - -If your work is specific to a single diagram type, it is a good idea to put the diagram type at the start of the description. This will help us keep release notes organized by a diagram type. - -> **Note** -> A new feature described in issue 2945 that adds a new arrow type called 'florbs' to state diagrams -> -> `feature/2945_state-diagram-new-arrow-florbs` - -> **💡 Tip** -> A bug described in issue 1123 that causes random ugly red text in multiple diagram types -> -> `bug/1123_fix_random_ugly_red_text` - -## Make changes - -Source code and the documentation are located \[`packages/mermaid`]\(() folder. -You may need to update both, depending on your task. - -Read our guides on [how to contribute to code](./code.md) and [how to contribute to documentation](./documentation.md). - -## Submit your pull request - -> **Note** -> Do not forget to push your changes -> -> ```bash -> git push -u origin docs/2910_update-contributing-guidelines -> ``` - -We make all changes via Pull Requests (PRs). Open a new one. - -Right now we are not following any strict rules about naming PRs. Give it a representative title and short description. There is also a [pull_request_template](https://github.com/mermaid-js/mermaid/blob/develop/.github/pull_request_template.md) which will help you with it. - -In case in its description contains a [magic comment](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) your PR will be automatically attached to the issue: - -```markdown -Resolves # -``` - -You can edit it if needed. - -## Congratulations - -You have successfully submitted your improvements! What is next? - -- PRs will be reviewed by active maintainers, who will provide feedback and request changes as needed. -- The maintainers will request a review from _knsv_, if necessary. -- Once the PR is approved, the maintainers will merge the PR into the `develop` branch. -- When a release is ready, the `release/x.x.x` branch will be created, extensively tested and knsv will be in charge of the release process. - -_knsv, Knut Sveidqvist_ is in charge of the final release process and the active maintainers are in charge of reviewing and merging most PRs. diff --git a/docs/config/img/python-mermaid-integration.png b/docs/ecosystem/img/python-mermaid-integration.png similarity index 100% rename from docs/config/img/python-mermaid-integration.png rename to docs/ecosystem/img/python-mermaid-integration.png