docs: new Documentation
This commit is contained in:
parent
cbcf7f8a11
commit
0da56a1249
|
@ -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.
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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"]
|
||||
}
|
||||
|
|
|
@ -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/
|
||||
|
||||
|
|
|
@ -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 .",
|
||||
|
|
|
@ -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"]
|
||||
}
|
|
@ -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": {
|
||||
|
|
|
@ -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');
|
||||
|
|
Loading…
Reference in New Issue