Adding MarkBind as an alternative docs option

[tlylt]

Fixes MarkBind/markbind#2072

Pending:

• MarkBind version bump for adding page-nav-print functionality
  • Update the action script and package.json
• Guide on how to use this as an alternative (Adapt this page https://nus-cs2103-ay2223s2.github.io/tp/Documentation.html)
• Final check to ensure everything works
  • Preview of the deployed docs: https://tlylt.github.io/ab3-docs-demo/index.html
  • Check that the print version of user and dev guide look ok

Finally:

• Instead of merging, someone with write access to this repo checkout and make a copy of tlylt:markbind-docs to se-edu:markbind-docs
• Some update is required from the CS2103T website to mention this option along side Jeykell, when mentioning tP docs

[canihasreview]

Click here to submit a new iteration when this PR is ready for review.

See this repository's contribution guide for more information.

[tlylt]

Hi @damithc, a quick status update:

• listed out the outline of the steps required, and some of the pending TODOs in the PR description
• Will likely publish a release on the MarkBind side to address the blocker here, so that the rest can ideally be done by next week
• have deployed a version of the adapted ab3 docs, mostly ready for a read-through/review of the presentation, at https://tlylt.github.io/ab3-docs-demo/index.html
• for the 2103T side do you have any plan on how instructions need to be updated once this docs work is completed?

[damithc]

Thanks for this initiative @tlylt
Added a few minor comments.

[damithc]

for the 2103T side do you have any plan on how instructions need to be updated once this docs work is completed?

For the time being (i.e., while this remains experimental), I can provide that information through the module website and se-edu/guides.

[tlylt]

Thanks @damithc for the review, I have updated the docs accordingly.

• can also preview it here https://tlylt.github.io/ab3-docs-demo/

Will also ask the rest of the MarkBind team to take a look to see if there are further edits needed.

[raysonkoh]

Thanks @tlylt for the hardwork in migrating the tp docs! Added some preliminary comments. Also, there seems to be an error in the syntax highlighting of the code blocks under tutorials/, more details in my comments.

[raysonkoh]

How about npm ci instead?

[tlylt]

If npm ci is used, then having a pin on the v4 version instead of the specific v4.1.0 may not make sense #156 (comment)

Because npm ci will not update the version of markbind-cli. Thoughts?

[raysonkoh]

Right, then should we remove the package-lock file since that would get overwritten after npm i anyway?

[tlylt]

hmm, it will only be overridden when there are changes to the version downloaded? If we remove it, do you think we should gitignore the package-lock? I'm not sure if that's a common practice.

[tlylt]

I would actually prefer pegging the version to a specific release for stability, and hence use npm ci. Tagging @damithc for comment on this.

[raysonkoh]

I would also prefer to peg to a specific release as future releases may introduce bugs. Using npm i may be risky.

[tlylt]

will change to npm ci for now

[tlylt]

Numbering issue

[damithc]

Added a few more minor comments.

[tlylt]

Hi @damithc, I left some comments replying to your queries. Can let me know what you think when you have time? I think I'm still keen to follow up on this and finish it by this semester. Will also do a final upgrade of the markbind version when v5 is released.

[damithc]

Sorry @tlylt , didn't realize you are waiting for my feedback:

A few other minor things:

Heading level mismatch?

UG and DG pdf version seems slightly shorter (i.e., fewer pages) in this version, which is good. The current AB3 uses orange color for headings. Should we do something similar in MarkBind version too (to make it look better, and also to show how to customize styles)?

And yes, get inputs from other MarkBind devs too.

For boxes, I'm wondering if the light or the seamless styles would make the content blend in with the main text more seamlessly. But this is a matter of taste and subjective.

In the end, we want to make the MarkBind version to look better (and editing not harder) than the current version or else there would be no incentive to switch.

[tlylt]

@damithc I have updated the markbind version required, and I think I have addressed the issues you brought up previously. As for making it more aesthetically pleasing than the current version: I think it looks fine to me as is......perhaps we can go with listing it as an alternative to see how it goes? I won't want to delay this further :)

Remaining TODOs listed in the PR description, and you can also preview the deployed site here: https://tlylt.github.io/ab3-docs-demo/index.html

🙆‍♂️

[damithc]

@tlylt Yup, let's get this sorted out before the next semester starts. I'll take a closer look soon. In the meantime, a few things I noticed:

• The home page should have the project name AddressBook Level-3 at the top
• Shall we make the DG part of the siteNav match the actual DG structure, similar to the UG?
• UML diagrams look exactly as before. Upgrade to the new PlantUML version didn't have any visible effect?