Refactor developer docs #1246
Refactor developer docs #1246
Conversation
Let's refactor the dev docs in the following ways to improve the overall organization: * Split up into separate pages such as setting up, design, workflow etc. * Refer to se-education.org/guides when possible * Improve phrasing, layout, formatting This reorganization also aim to increase consistency with other sister projects such as RepoSense
|
Ready for review |
ang-zeyu
left a comment
ang-zeyu
left a comment
There was a problem hiding this comment.
Looks a lot cleaner now 👍
I gave the parts on build / release process a quick glance only, as it will be substantially changed soon.
The page on project structure as well, since the merge from /vue-strap is coming in
docs/devGuide/workflow.md
Outdated
| Install developer dependencies (ESLint, related plugins) in your cloned markbind and markbind-cli repositories. | ||
|
|
||
| ```{.no-line-numbers} | ||
| $ npm install --only=dev |
There was a problem hiding this comment.
this shouldn't be neccessary anymore, assuming they did a npm install/link
docs/devGuide/workflow.md
Outdated
| Before making a commit or pull request, you should lint your code by running the following commands from the root of your project: | ||
|
|
||
| * To lint a specific file: `./node_modules/.bin/eslint path/to/specificfile.js` | ||
| * To lint all files: `./node_modules/.bin/eslint .` |
There was a problem hiding this comment.
let's update this (all files) to use npm run lint
docs/devGuide/workflow.md
Outdated
|
|
||
| It is also possible to auto-fix some (not all) style errors: | ||
| * Add the `--fix` flag to correct any fixable style errors<br> | ||
| e.g., `./node_modules/.bin/eslint . --fix` |
There was a problem hiding this comment.
npm run lintfix (without the need for --fix as well)
| 1. **Install dependencies** by running `npm install` in the root folder of your cloned repo. | ||
| 1. **To bind your cloned version of MarkBind to your console** (instead of the released version of MarkBind), run `npm link` in the root folder of the cloned repo. | ||
|
|
||
| <box type="tip" seamless> |
There was a problem hiding this comment.
should we align the boxes? looks a little strange:
There was a problem hiding this comment.
The boxes are nested at the same level as their logical level in the hierarchy. The first one is outside of the list while the second one applies to the 3rd item in the list only.
In addition, if we don't indent the 2nd box, it will break list numbering. i.e., 4th item will become 1.
|
Thx for the review @ang-zeyu. I've updated the linting instructions as suggested. Please check in case I misunderstood your comment. |
ang-zeyu
left a comment
ang-zeyu
left a comment
There was a problem hiding this comment.
Lgtm otherwise 👍 Let's squash the commits as well!
docs/devGuide/workflow.md
Outdated
|
|
||
| * You can start by looking through [these issues](https://github.com/MarkBind/markbind/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+sort%3Acomments-desc) marked <span href="" class="badge" style="color:white; background-color: #7057FF;">good first issue</span>. Don't do more than one of them though. | ||
| * As we squash the commits when merging a PR, there is ==no need to follow a strict commit organization or write elaborate commit messages for each commit==. | ||
| * You can refer to the [_Design_](design.html) page to learn about the design and implementation of RepoSense. |
2 participants
What is the purpose of this pull request? (put "X" next to an item, remove the rest)
• [x] Documentation update
What is the rationale for this request?, What changes did you make? (Give an overview)
See the proposed commit message.
Testing instructions:
Read the DG via the Netlify preview of the PR.
Proposed commit message: (wrap lines at 72 characters)