From 0da56a1249022aa5249a9a947ebfab8d02716764 Mon Sep 17 00:00:00 2001 From: Emerson Bottero Date: Sat, 15 Oct 2022 00:50:57 -0300 Subject: [PATCH] docs: new Documentation --- .github/gh-pages-publish.yml | 21 +++++++++++++++++++++ .github/workflows/docs.yml | 6 +++--- .github/workflows/lint.yml | 2 +- .lintstagedrc.json | 2 -- CONTRIBUTING.md | 14 +++++++------- package.json | 1 - packages/mermaid/.lintstagedrc.json | 6 ++++++ packages/mermaid/package.json | 15 ++++++++------- packages/mermaid/src/docs.mts | 2 +- 9 files changed, 47 insertions(+), 22 deletions(-) create mode 100644 .github/gh-pages-publish.yml create mode 100644 packages/mermaid/.lintstagedrc.json diff --git a/.github/gh-pages-publish.yml b/.github/gh-pages-publish.yml new file mode 100644 index 000000000..de87e6a3b --- /dev/null +++ b/.github/gh-pages-publish.yml @@ -0,0 +1,21 @@ +name: Build and Deploy Docs +on: [push] +permissions: + contents: write +jobs: + build-and-deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout 🛎️ + uses: actions/checkout@v3 + + - name: Install and Build 🔧 # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built. + run: | + pnpm install + cd ./packages/mermaid + pnpm docs:bundle + - name: Deploy 🚀📕 + uses: JamesIves/github-pages-deploy-action@v4.3.3 + with: + branch: gh-pages # The branch the action should deploy to. + folder: packages/mermaid/docs/.vitepress/dist # The folder the action should deploy. diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a7ad03a7a..f316c47c7 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,12 +5,12 @@ on: branches: - develop paths: - - 'packages/mermaid/src/docs/**/*' + - 'packages/mermaid/docs/**/*' pull_request: branches: - develop paths: - - 'packages/mermaid/src/docs/**/*' + - 'packages/mermaid/docs/**/*' jobs: spellcheck: name: 'Docs: Spellcheck' @@ -24,5 +24,5 @@ jobs: node-version: '16' - run: npm install -g cspell name: Install cSpell - - run: cspell --config ./cSpell.json "packages/mermaid/src/docs/**/*.md" --no-progress + - run: cspell --config ./cSpell.json "packages/mermaid/docs/**/*.md" --no-progress name: Run cSpell diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 9adbb177c..204350dd1 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -39,4 +39,4 @@ jobs: run: pnpm run lint - name: Verify Docs - run: pnpm run docs:verify + run: cd .\packages\mermaid\ && pnpm run docs:verify diff --git a/.lintstagedrc.json b/.lintstagedrc.json index be6e92770..8d5e1ca4a 100644 --- a/.lintstagedrc.json +++ b/.lintstagedrc.json @@ -1,6 +1,4 @@ { - "packages/mermaid/src/docs/**": ["pnpm run docs:build --git"], - "packages/mermaid/src/docs.mts": ["pnpm run docs:build --git"], "*.{ts,js,json,html,md,mts}": ["eslint --fix", "prettier --write"], "*.jison": ["pnpm run lint:jison"] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ed436a8d1..843e19fd9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,7 @@ We make all changes via pull requests. As we have many pull requests from develo - Large changes reviewed by knsv or other developer asked to review by knsv - Smaller low-risk changes like dependencies, documentation, etc. can be merged by active collaborators -- Documentation (updates to the `src/docs` folder is also allowed via direct commits) +- Documentation (updates to the `package/mermaid/docs` folder is also allowed via direct commits) To commit code, create a branch, let it start with the type like feature or bug followed by the issue number for reference and some describing text. @@ -50,16 +50,16 @@ Less strict here, it is OK to commit directly in the `develop` branch if you are The documentation is written in **Markdown**. For more information about Markdown [see the GitHub Markdown help page](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). -### Documentation source files are in [`/packages/mermaid/src/docs`](packages/mermaid/src/docs) +### Documentation source files are in [`/packages/mermaid/docs`](packages/mermaid/docs) -The source files for the project documentation are located in the [`/packages/mermaid/src/docs`](packages/mermaid/src/docs) directory. This is where you should make changes. -The files under `/packages/mermaid/src/docs` are processed to generate the published documentation, and the resulting files are put into the `/docs` directory. +The source files for the project documentation are located in the [`/packages/mermaid/docs`](packages/mermaid/docs) directory. This is where you should make changes. +The files under `/packages/mermaid/docs` are processed to generate the published documentation, and the resulting files are put into the `/docs` directory. ```mermaid flowchart LR classDef default fill:#fff,color:black,stroke:black - source["files in /packages/mermaid/src/docs\n(changes should be done here)"] -- automatic processing\nto generate the final documentation--> published["files in /docs\ndisplayed on the official documentation site"] + source["files in /packages/mermaid/docs\n(changes should be done here)"] -- automatic processing\nto generate the final documentation--> published["files in /docs\ndisplayed on the official documentation site"] ``` @@ -148,11 +148,11 @@ it('should render forks and joins', () => { Finally, if it is not in the documentation, no one will know about it and then **no one will use it**. Wouldn't that be sad? With all the effort that was put into the feature? -The source files for documentation are in `/packages/mermaid/src/docs` and are written in markdown. Just pick the right section and start typing. See the [Committing Documentation](#committing-documentation) section for more about how the documentation is generated. +The source files for documentation are in `/packages/mermaid/docs` and are written in markdown. Just pick the right section and start typing. See the [Committing Documentation](#committing-documentation) section for more about how the documentation is generated. #### Adding to or changing the documentation organization -If you want to add a new section or change the organization (structure), then you need to make sure to **change the side navigation** in `src/docs/_sidebar.md`. +If you want to add a new section or change the organization (structure), then you need to make sure to **change the side navigation** in `docs/_sidebar.md`. When changes are committed and then released, they become part of the `master` branch and become part of the published documentation on https://mermaid-js.github.io/mermaid/ diff --git a/package.json b/package.json index 7a25c4374..b8822bd93 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,6 @@ "build:watch": "pnpm build:vite --watch", "build": "pnpm run -r clean && concurrently \"pnpm build:vite\" \"pnpm build:types\"", "dev": "concurrently \"pnpm build:vite --watch\" \"ts-node-esm .vite/server.ts\"", - "todo-postbuild": "documentation build src/mermaidAPI.ts src/config.ts src/defaultConfig.ts --shallow -f md --markdown-toc false > src/docs/Setup.md && prettier --write src/docs/Setup.md", "release": "pnpm build", "lint": "eslint --cache --ignore-path .gitignore . && pnpm lint:jison && prettier --check .", "lint:fix": "eslint --fix --ignore-path .gitignore . && prettier --write .", diff --git a/packages/mermaid/.lintstagedrc.json b/packages/mermaid/.lintstagedrc.json new file mode 100644 index 000000000..d199320ef --- /dev/null +++ b/packages/mermaid/.lintstagedrc.json @@ -0,0 +1,6 @@ +{ + "packages/mermaid/docs/**": ["pnpm run docs:build --git"], + "packages/mermaid/docs.mts": ["pnpm run docs:build --git"], + "*.{ts,js,json,html,md,mts}": ["eslint --fix", "prettier --write"], + "*.jison": ["pnpm run lint:jison"] +} diff --git a/packages/mermaid/package.json b/packages/mermaid/package.json index 34d9ea67d..95a9b53f1 100644 --- a/packages/mermaid/package.json +++ b/packages/mermaid/package.json @@ -27,26 +27,27 @@ "clean": "rimraf dist", "build:code": "node .esbuild/esbuild.cjs", "build:types": "tsc -p ./tsconfig.json --emitDeclarationOnly", - "build:watch": "yarn build:code --watch", - "build:esbuild": "concurrently \"yarn build:code\" \"yarn build:types\"", - "build": "yarn clean; yarn build:esbuild", + "build:watch": "pnpm build:code --watch", + "build:esbuild": "concurrently \"pnpm build:code\" \"pnpm build:types\"", + "build": "pnpm clean; pnpm build:esbuild", "dev": "node .esbuild/serve.cjs", + "predocs:build": "rimraf docs/.vitepress/dist", "docs:build": "ts-node-esm src/docs.mts", - "docs:verify": "yarn docs:build --verify", + "docs:verify": "pnpm docs:build --verify", "docs:code": "typedoc --plugin typedoc-plugin-markdown --readme none --hideBreadcrumbs --hideInPageTOC --namedAnchors --out docs/config/setup --entryPointStrategy expand src/defaultConfig.ts src/config.ts src/mermaidAPI.ts", "predocs:dev": "pnpm docs:code", "docs:dev": "vitepress dev docs", "predocs:bundle": "pnpm docs:code", "docs:bundle": "vitepress build docs", "docs:serve": "vitepress serve docs", - "release": "yarn build", - "lint": "eslint --cache --ignore-path .gitignore . && yarn lint:jison && prettier --check .", + "release": "pnpm build", + "lint": "eslint --cache --ignore-path .gitignore . && pnpm lint:jison && prettier --check .", "lint:fix": "eslint --fix --ignore-path .gitignore . && prettier --write .", "lint:jison": "ts-node-esm src/jison/lint.mts", "cypress": "cypress run", "cypress:open": "cypress open", "e2e": "start-server-and-test dev http://localhost:9000/ cypress", - "todo-prepare": "concurrently \"husky install\" \"yarn build\"", + "todo-prepare": "concurrently \"husky install\" \"pnpm build\"", "pre-commit": "lint-staged" }, "repository": { diff --git a/packages/mermaid/src/docs.mts b/packages/mermaid/src/docs.mts index 088a50bf9..d350d9970 100644 --- a/packages/mermaid/src/docs.mts +++ b/packages/mermaid/src/docs.mts @@ -56,7 +56,7 @@ const LOGMSG_TRANSFORMED = 'transformed'; const LOGMSG_TO_BE_TRANSFORMED = 'to be transformed'; const LOGMSG_COPIED = `, and copied to ${FINAL_DOCS_DIR}`; -const WARN_DOCSDIR_DOESNT_MATCH = `Changed files were transformed in ${SOURCE_DOCS_DIR} but do not match the files in ${FINAL_DOCS_DIR}. Please run yarn docs:build after making changes to ${SOURCE_DOCS_DIR} to update the ${FINAL_DOCS_DIR} directory with the transformed files.`; +const WARN_DOCSDIR_DOESNT_MATCH = `Changed files were transformed in ${SOURCE_DOCS_DIR} but do not match the files in ${FINAL_DOCS_DIR}. Please run pnpm docs:build after making changes to ${SOURCE_DOCS_DIR} to update the ${FINAL_DOCS_DIR} directory with the transformed files.`; const verifyOnly: boolean = process.argv.includes('--verify'); const git: boolean = process.argv.includes('--git');