Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Split development documentation into several pages #4744

Conversation

nirname
Copy link
Contributor

@nirname nirname commented Aug 17, 2023

📑 Summary

Simplifying development documentation

Related:

📏 Design Decisions

Current development pages were far to long to read and understand:

  • Split development page into several pages, previous one was far too big to read it briefly
  • Nested sections at the left menu buttons caused Prev Page and Next Page buttons to be wrong
  • Sections inside development pages are 2nd level now (heading 2) and visible at the right menu
  • Added some missing commands to start development
  • Removed links to obsolete n00b-overview page and the page itself
  • Added documentation for development in Docker and cross links between host and docker installation guides
  • Fixed top menu (added link to contribution sections)
  • Squashed some sections of introduction page together as they repeated each other
  • Some of the headings changed their levels to more consistent structure

Other things will be done in upcoming requests such as:

  • Removing n00b from file names
  • Making shorter version of development pages (aka Quick Start Guide) and updating CONTRUBITION.md
  • Adding section 'Why use Mermaid'

📋 Tasks

Make sure you

@codecov
Copy link

codecov bot commented Aug 17, 2023

Codecov Report

Merging #4744 (cee2a45) into develop (b85c011) will increase coverage by 0.08%.
Report is 105 commits behind head on develop.
The diff coverage is n/a.

Additional details and impacted files

Impacted file tree graph

@@             Coverage Diff             @@
##           develop    #4744      +/-   ##
===========================================
+ Coverage    77.04%   77.13%   +0.08%     
===========================================
  Files          144      146       +2     
  Lines        14565    14561       -4     
  Branches       586      586              
===========================================
+ Hits         11221    11231      +10     
+ Misses        3233     3217      -16     
- Partials       111      113       +2     
Flag Coverage Δ
e2e 84.03% <ø> (+0.13%) ⬆️
unit 45.55% <ø> (+0.21%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

see 18 files with indirect coverage changes

@nirname nirname force-pushed the docs/2910_split-development-documentation branch from 7494ab5 to ef9e899 Compare August 17, 2023 22:33
@nirname
Copy link
Contributor Author

nirname commented Aug 17, 2023

@Yokozuna59 I ensured that "Adding new diagram" is a separate file, and a separate line in the left menu. Editing it is harmless, there is no soon changes to this file in this or upcoming PR's. Edit it should you need to

@nirname nirname marked this pull request as ready for review August 17, 2023 22:38
…the sidebar menu

United similar sections at the intro page

Fix spelling

Update docs
@nirname nirname force-pushed the docs/2910_split-development-documentation branch from 3560b35 to 3411308 Compare August 17, 2023 23:17
packages/mermaid/src/docs/.vitepress/theme/redirect.ts Outdated Show resolved Hide resolved
docs/community/docker-development.md Show resolved Hide resolved
docs/community/documentation.md Show resolved Hide resolved
packages/mermaid/src/docs/intro/index.md Outdated Show resolved Hide resolved
packages/mermaid/src/docs/intro/index.md Outdated Show resolved Hide resolved
packages/mermaid/src/docs/community/documentation.md Outdated Show resolved Hide resolved
packages/mermaid/src/docs/community/documentation.md Outdated Show resolved Hide resolved
Copy link
Member

@aloisklink aloisklink left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for splitting up the #4596 PR! This is a lot easier to review 😄

Other than @sidharthv96's comments, it looks good to me, so I'll let @sidharthv96 officially "Approve" this PR when it's done.

Btw, for future PRs (it's not worth doing for this PR), it would be even easier to review if you split up the commits where you

  • move lines between files and where you
  • modify the lines.

That way us reviewers can easily see which lines you've just copied over, and we can ignore them, and only focus on the lines that have changed (you can then even write in your PR description to tell us to ignore some commits 😉)


Hmmm, weird, I swear docs/* is in the PR labeler config, but for some reason the Area: Documentation label didn't get automatically applied.

'Area: Documentation': ['docs/*']

Maybe the labeller action doesn't work on PRs from forks? Oh well, it's not too difficult to manually label PRs.

packages/mermaid/src/docs/.vitepress/theme/redirect.ts Outdated Show resolved Hide resolved
packages/mermaid/src/docs/community/docker-development.md Outdated Show resolved Hide resolved
packages/mermaid/src/docs/community/documentation.md Outdated Show resolved Hide resolved
packages/mermaid/src/docs/intro/index.md Outdated Show resolved Hide resolved
@nirname nirname force-pushed the docs/2910_split-development-documentation branch from bb093b9 to cee2a45 Compare August 22, 2023 21:30
@sidharthv96 sidharthv96 added this pull request to the merge queue Aug 23, 2023
Merged via the queue into mermaid-js:develop with commit bd98da1 Aug 23, 2023
13 checks passed
fuxingloh referenced this pull request in fuxingloh/contented Aug 28, 2023
[![Mend
Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)

This PR contains the following updates:

| Package | Change | Age | Adoption | Passing | Confidence |
|---|---|---|---|---|---|
| [mermaid](https://togithub.com/mermaid-js/mermaid) | [`10.3.1` ->
`10.4.0`](https://renovatebot.com/diffs/npm/mermaid/10.3.1/10.4.0) |
[![age](https://developer.mend.io/api/mc/badges/age/npm/mermaid/10.4.0?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![adoption](https://developer.mend.io/api/mc/badges/adoption/npm/mermaid/10.4.0?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![passing](https://developer.mend.io/api/mc/badges/compatibility/npm/mermaid/10.3.1/10.4.0?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/mermaid/10.3.1/10.4.0?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|

---

### Release Notes

<details>
<summary>mermaid-js/mermaid (mermaid)</summary>

###
[`v10.4.0`](https://togithub.com/mermaid-js/mermaid/releases/tag/v10.4.0)

[Compare
Source](https://togithub.com/mermaid-js/mermaid/compare/v10.3.1...v10.4.0)

#### Features

- feat: Support config in frontmatter. by
[@&#8203;sidharthv96](https://togithub.com/sidharthv96) in
[https://github.com/mermaid-js/mermaid/pull/4750](https://togithub.com/mermaid-js/mermaid/pull/4750)
- feat(sankey): Show values by
[@&#8203;sidharthv96](https://togithub.com/sidharthv96) in
[https://github.com/mermaid-js/mermaid/pull/4748](https://togithub.com/mermaid-js/mermaid/pull/4748)

#### Docs

- docs: Add development example page. by
[@&#8203;sidharthv96](https://togithub.com/sidharthv96) in
[https://github.com/mermaid-js/mermaid/pull/4714](https://togithub.com/mermaid-js/mermaid/pull/4714)
- Documentation for
[#&#8203;2509](https://togithub.com/mermaid-js/mermaid/issues/2509) by
[@&#8203;jason-curtis](https://togithub.com/jason-curtis) in
[https://github.com/mermaid-js/mermaid/pull/4740](https://togithub.com/mermaid-js/mermaid/pull/4740)
- Fixes to Docs sidebar, main page and badges by
[@&#8203;nirname](https://togithub.com/nirname) in
[https://github.com/mermaid-js/mermaid/pull/4742](https://togithub.com/mermaid-js/mermaid/pull/4742)
- Split development documentation into several pages by
[@&#8203;nirname](https://togithub.com/nirname) in
[https://github.com/mermaid-js/mermaid/pull/4744](https://togithub.com/mermaid-js/mermaid/pull/4744)
- Docs: update Latest News section by
[@&#8203;huynhicode](https://togithub.com/huynhicode) in
[https://github.com/mermaid-js/mermaid/pull/4768](https://togithub.com/mermaid-js/mermaid/pull/4768)

#### Chores

- Update all minor dependencies (minor) by
[@&#8203;renovate](https://togithub.com/renovate) in
[https://github.com/mermaid-js/mermaid/pull/4732](https://togithub.com/mermaid-js/mermaid/pull/4732)
- Update all patch dependencies (patch) by
[@&#8203;renovate](https://togithub.com/renovate) in
[https://github.com/mermaid-js/mermaid/pull/4731](https://togithub.com/mermaid-js/mermaid/pull/4731)
- convert `assignWithDepth` to TS by
[@&#8203;Yokozuna59](https://togithub.com/Yokozuna59) in
[https://github.com/mermaid-js/mermaid/pull/4717](https://togithub.com/mermaid-js/mermaid/pull/4717)
- convert `diagrams/common/svgDrawCommon.js` to ts by
[@&#8203;Yokozuna59](https://togithub.com/Yokozuna59) in
[https://github.com/mermaid-js/mermaid/pull/4724](https://togithub.com/mermaid-js/mermaid/pull/4724)
- ci(release-drafter): add more release notes categories by
[@&#8203;aloisklink](https://togithub.com/aloisklink) in
[https://github.com/mermaid-js/mermaid/pull/4752](https://togithub.com/mermaid-js/mermaid/pull/4752)
- chore(deps): update all patch dependencies (patch) by
[@&#8203;renovate](https://togithub.com/renovate) in
[https://github.com/mermaid-js/mermaid/pull/4753](https://togithub.com/mermaid-js/mermaid/pull/4753)
- standardized pie definitions by
[@&#8203;Yokozuna59](https://togithub.com/Yokozuna59) in
[https://github.com/mermaid-js/mermaid/pull/4501](https://togithub.com/mermaid-js/mermaid/pull/4501)
- Remove Circular Dependencies by
[@&#8203;sidharthv96](https://togithub.com/sidharthv96) in
[https://github.com/mermaid-js/mermaid/pull/4761](https://togithub.com/mermaid-js/mermaid/pull/4761)
- chore: Enforce type imports by
[@&#8203;sidharthv96](https://togithub.com/sidharthv96) in
[https://github.com/mermaid-js/mermaid/pull/4763](https://togithub.com/mermaid-js/mermaid/pull/4763)
- chore: Preview PRs with mermaid-live-editor on Netlify by
[@&#8203;sidharthv96](https://togithub.com/sidharthv96) in
[https://github.com/mermaid-js/mermaid/pull/4769](https://togithub.com/mermaid-js/mermaid/pull/4769)

#### New Contributors

- [@&#8203;jason-curtis](https://togithub.com/jason-curtis) made their
first contribution in
[https://github.com/mermaid-js/mermaid/pull/4740](https://togithub.com/mermaid-js/mermaid/pull/4740)

**Full Changelog**:
mermaid-js/mermaid@v10.3.1...v10.4.0

</details>

---

### Configuration

📅 **Schedule**: Branch creation - At any time (no schedule defined),
Automerge - At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you
are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the
rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update
again.

---

- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box

---

This PR has been generated by [Mend
Renovate](https://www.mend.io/free-developer-tools/renovate/). View
repository job log
[here](https://developer.mend.io/github/levaintech/contented).

<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNi41Ni4wIiwidXBkYXRlZEluVmVyIjoiMzYuNTYuMCIsInRhcmdldEJyYW5jaCI6Im1haW4ifQ==-->

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants