MarkBind Template for Software Project Documentation

[KevinEyo1]

What is the purpose of this pull request?

• [ ] Documentation update
• [ ] Bug fix
• [x] Feature addition or enhancement
• [ ] Code maintenance
• [ ] DevOps
• [ ] Improve developer experience
• [ ] Others, please explain:

Overview of changes:

2384

Adapted files from ab3 repo for project documentation template. Added deployed netlify site for project template to templates.md file in UG docs.

Anything you'd like to highlight/discuss: Currently deployed site on templates.md is hosted on personal github repo and account. Parts of ab3 still present in new template such as diagrams and parts of Dev Guide as I am not sure whether to completely remove them or not, since after removing them I find it hard to fully show examples of how those sections should look like. The expectation could be for it to be that minimal. I am also unsure of the approach by which to do the pages in the sense of the following example: For a section listing benefits of product, to write benefits of an example product like meeting scheduler, or be more meta in a sense and literally have a list like "List of benefits: Benefit 1, Benefit 2, Benefit3".

Testing instructions:

markbind init --template project

Proposed commit message: (wrap lines at 72 characters) MarkBind templates: add a project-specific template

MarkBind has default and minimal templates.

MarkBind lacks a specific template for project documentation, limiting its appeal to users seeking specialized starting points.

Creating a new template for such users enhances MarkBind's usability by providing a tailored starting point for creating project documentation, encouraging more users to choose MarkBind for their documentation needs.

Let's add a project template option during MarkBind initialization that generates a template specifically to project documentation needs, with a User Guide and Developer Guide.

This approach directly addresses the gap for specialized documentation templates, making MarkBind a more attractive option for project maintainers.

---

Checklist: :ballot_box_with_check:

• [x] Updated the documentation for feature additions and enhancements
• [x] Added tests for bug fixes or features
• [x] Linked all related issues
• [x] No unrelated changes

---

Reviewer checklist:

Indicate the SEMVER impact of the PR:

• [ ] Major (when you make incompatible API changes)
• [x] Minor (when you add functionality in a backward compatible manner)
• [ ] Patch (when you make backward compatible bug fixes)

At the end of the review, please label the PR with the appropriate label: r.Major, r.Minor, r.Patch.

Breaking change release note preparation (if applicable):

• To be included in the release note for any feature that is made obsolete/breaking

Give a brief explanation note about:

• what was the old feature that was made obsolete
• any replacement feature (if any), and
• how the author should modify his website to migrate from the old feature to the replacement feature (if possible).

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 51.11%. Comparing base (e95e588) to head (8e45510).

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #2400 +/- ## ======================================= Coverage 51.11% 51.11% ======================================= Files 124 124 Lines 5355 5355 Branches 1152 1152 ======================================= Hits 2737 2737 Misses 2328 2328 Partials 290 290 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[KevinEyo1]

As discussed with @damithc, will go with the approach of keeping the site minimal, using placeholder picture with captions and dummy texts.

[EltonGohJH]

For now, lets fix the bugs. Also, let me double check on the content template.

[KevinEyo1]

For the testing files of the new template, I generated using the updatetest script, but it creates the files with a timestamp, such that when it does the comparison with newly created files, the timestamp generated is different. Do you know how to solve this @EltonGohJH ? I checked the files for the other templates and there aren't any timestamps, which would imply the newly created files used for comparison doesnt generate timestamps, unlike the testing of the new template, which is peculiar.

[EltonGohJH]

As discussed, you can remove the footer with the timestamp.

Also, remember to update your netlify template.

I realised that your commit message can be improved. (Feel free to use chatgpt) Follow this format. https://se-education.org/guides/conventions/git.html

[EltonGohJH]

@kaixin-hc @yucheng11122017 @itsyme @lhw-1

https://markbind-template-project.netlify.app/

I am thinking whether this template is minimal enough to be used in a general case? What do you all think about it? Important consideration is that we hope that CS2103 students can adapt this template for their use case too. (Removing too much may hinder them in using this template?)

[yucheng11122017]

I am thinking whether this template is minimal enough to be used in a general case?

Hmmm imo, the user guide and home seems ok and minimal enough. I have some doubts about the developer guide though - in particular the design subsection which seems a bit too specific. I like the parts that show off markbind's functionality like puml diagrams and so on but the rest can be deleted i think. The two appendixes can be removed as well I believe. The three tutorials also seem too specific to AB3

Important consideration is that we hope that CS2103 students can adapt this template for their use case too. (Removing too much may hinder them in using this template?)

tbh I think its ok for them to use this template since there is already an existing one made by yongliang which they can clone and work on more easily.

[itsyme]

I agree with @yucheng11122017 about the dev guide section, perhaps we could phrase it as "You can add pUml diagrams such as below! ..." to showcase MarkBind's features rather than the current verbosity of the example. I think the rest of the template is fine besides some minor nits like standardising some headers (e.g. X Feature -> Feature X)!

[tlylt]

I am thinking whether this template is minimal enough to be used in a general case?

can probably reduce the content

[KevinEyo1]

I updated the commit message body as well as completely removed any traces of ab3 as per mentioned in the comments. My thinking in leaving some traces was to try to strike a balance between reducing traces of ab3 and giving a clearer picture of what would a more realistic site would look like. I agree that removing and minimizing content would definitely be better considering it is just a template.

[kaixin-hc]

Thanks @KevinEyo1 for your work . BTW - please take a look at the files you have committed - I think you have wrongly committed roughly a hundred files.

I've noticed this happen sometimes with updatetest, something about your environment being outdated. It's mentioned in one of the other issues but I can't remember which one; either way, these font files should definitely not be a part of this PR

[KevinEyo1]

Thanks for your comment @kaixin-hc , can I clarify if you are referring to the files in packages\cli\test\functional\test_site_templates\test_project\expected\markbind ? I didn't touch it since I checked against the respective folders for the default and minimal template and they also had those files originally.

[kaixin-hc]

Thanks for raising that! You might be right in this case, I confused it with another issue I saw before. I don't have time for an extensive review but let me flag a few more things for you to look at (user-perspective, not so much code)

[KevinEyo1]

Thanks @kaixin-hc for all the comments. I will work on it and try my best to polish it as much as possible.

[tlylt]

I see that this PR includes the test site for the new template, but https://github.com/MarkBind/markbind/pull/2398 doesn't. 3282 folks may want to discuss and see if a test site has to be added for every new template as there are some pros & cons (number of file changes, speed of tests etc) to weigh here. Perhaps since we don't have a SOP on what should be done when adding a new template, which should go into our DG if we intend to continue doing so.

[KevinEyo1]

One thing that I was too lazy to keep marking is the use of . I'm not sure what is the purpose of having that and I'll actually prefer not to have it.

@yucheng11122017 Can i clarify what you are referring to when you mention "use of"?

[damithc]

@yucheng11122017 Can i clarify what you are referring to when you mention "use of"?

... use of <page-nav-print /> (the last part was swallowed by GitHub sanitizing).