Tweak the content further

* Remove unused images * Replace frontmatter with --- * Change box style light -> seamless * Tweak the Documentation.md * Tweak other content for nits * Ignore logs * Add missing puml files
se-edu · Sep 11, 2023 · d39eadb · d39eadb
1 parent 220c7ff
commit d39eadb
Show file tree

Hide file tree

Showing 45 changed files with 146 additions and 207 deletions.
diff --git a/.gitignore b/.gitignore
@@ -21,3 +21,4 @@ src/test/data/sandbox/
 # MacOS custom attributes files created by Finder
 .DS_Store
 docs/_site/
+docs/_markbind/logs/
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -20,4 +20,4 @@ _site/
 # IDE configs
 .vscode/
 .idea/*
-*.iml
+*.iml
diff --git a/docs/AboutUs.md b/docs/AboutUs.md
@@ -1,7 +1,7 @@
-<frontmatter>
+---
  layout: default.md
  title: "About Us"
-</frontmatter>
+---
 
 # About Us
 

diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -1,7 +1,7 @@
-<frontmatter>
+---
  layout: default.md
  title: "Configuration guide"
-</frontmatter>
+---
 
 # Configuration guide
 

diff --git a/docs/DevOps.md b/docs/DevOps.md
@@ -1,9 +1,8 @@
-<frontmatter>
+---
  layout: default.md
  title: "DevOps guide"
  pageNav: 3
- pageNavTitle: "Table Of Content"
-</frontmatter>
+---
 
 # DevOps guide
 

diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md
@@ -1,9 +1,8 @@
-<frontmatter>
+---
  layout: default.md
  title: "Developer Guide"
  pageNav: 3
- pageNavTitle: "Table Of Content"
-</frontmatter>
+---
 
 # AB-3 Developer Guide
 
@@ -14,7 +13,7 @@
 
 ## **Acknowledgements**
 
-* list here sources of all reused/adapted ideas, code, documentation, and third-party libraries -- include links to the original source as well
+_{ list here sources of all reused/adapted ideas, code, documentation, and third-party libraries -- include links to the original source as well }_
 
 --------------------------------------------------------------------------------------------------------------------
 
@@ -26,12 +25,6 @@ Refer to the guide [_Setting up and getting started_](SettingUp.md).
 
 ## **Design**
 
-<box type="tip" seamless>
-
-**Tip:** The `.puml` files used to create diagrams in this document can be found in the `docs/diagrams` folder. Refer to [_markbind/user-guide/diagrams **Using PlantUML with MarkBind**_](https://markbind.org/userGuide/components/imagesAndDiagrams.html#diagrams)
-to learn how to create and edit diagrams.
-</box>
-
 ### Architecture
 
 <puml src="diagrams/ArchitectureDiagram.puml" width="280" />
@@ -99,9 +92,9 @@ Here's a (partial) class diagram of the `Logic` component:
 
 The sequence diagram below illustrates the interactions within the `Logic` component, taking `execute("delete 1")` API call as an example.
 
-![Interactions Inside the Logic Component for the `delete 1` Command](images/DeleteSequenceDiagram.png)
+<puml src="diagrams/DeleteSequenceDiagram.puml" alt="Interactions Inside the Logic Component for the `delete 1` Command" />
 
-<box type="info" light>
+<box type="info" seamless>
 
 **Note:** The lifeline for `DeleteCommandParser` should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.
 </box>
@@ -134,7 +127,7 @@ The `Model` component,
 * stores a `UserPref` object that represents the user’s preferences. This is exposed to the outside as a `ReadOnlyUserPref` objects.
 * does not depend on any of the other three components (as the `Model` represents data entities of the domain, they should make sense on their own without depending on other components)
 
-<box type="info" light>
+<box type="info" seamless>
 
 **Note:** An alternative (arguably, a more OOP) model is given below. It has a `Tag` list in the `AddressBook`, which `Person` references. This allows `AddressBook` to only require one `Tag` object per unique tag, instead of each `Person` needing their own `Tag` objects.<br>
 
@@ -180,28 +173,28 @@ Given below is an example usage scenario and how the undo/redo mechanism behaves
 
 Step 1. The user launches the application for the first time. The `VersionedAddressBook` will be initialized with the initial address book state, and the `currentStatePointer` pointing to that single address book state.
 
-![UndoRedoState0](images/UndoRedoState0.png)
+<puml src="diagrams/UndoRedoState0.puml" alt="UndoRedoState0" />
 
 Step 2. The user executes `delete 5` command to delete the 5th person in the address book. The `delete` command calls `Model#commitAddressBook()`, causing the modified state of the address book after the `delete 5` command executes to be saved in the `addressBookStateList`, and the `currentStatePointer` is shifted to the newly inserted address book state.
 
-![UndoRedoState1](images/UndoRedoState1.png)
+<puml src="diagrams/UndoRedoState1.puml" alt="UndoRedoState1" />
 
 Step 3. The user executes `add n/David …` to add a new person. The `add` command also calls `Model#commitAddressBook()`, causing another modified address book state to be saved into the `addressBookStateList`.
 
-![UndoRedoState2](images/UndoRedoState2.png)
+<puml src="diagrams/UndoRedoState2.puml" alt="UndoRedoState2" />
 
-<box type="info" light>
+<box type="info" seamless>
 
 **Note:** If a command fails its execution, it will not call `Model#commitAddressBook()`, so the address book state will not be saved into the `addressBookStateList`.
 
 </box>
 
 Step 4. The user now decides that adding the person was a mistake, and decides to undo that action by executing the `undo` command. The `undo` command will call `Model#undoAddressBook()`, which will shift the `currentStatePointer` once to the left, pointing it to the previous address book state, and restores the address book to that state.
 
-![UndoRedoState3](images/UndoRedoState3.png)
+<puml src="diagrams/UndoRedoState3.puml" alt="UndoRedoState3" />
 
 
-<box type="info" light>
+<box type="info" seamless>
 
 **Note:** If the `currentStatePointer` is at index 0, pointing to the initial AddressBook state, then there are no previous AddressBook states to restore. The `undo` command uses `Model#canUndoAddressBook()` to check if this is the case. If so, it will return an error to the user rather
 than attempting to perform the undo.
@@ -212,27 +205,27 @@ The following sequence diagram shows how the undo operation works:
 
 <puml src="diagrams/UndoSequenceDiagram.puml" alt="UndoSequenceDiagram" />
 
-<box type="info" light>
+<box type="info" seamless>
 
 **Note:** The lifeline for `UndoCommand` should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.
 
 </box>
 
 The `redo` command does the opposite — it calls `Model#redoAddressBook()`, which shifts the `currentStatePointer` once to the right, pointing to the previously undone state, and restores the address book to that state.
 
-<box type="info" light>
+<box type="info" seamless>
 
 **Note:** If the `currentStatePointer` is at index `addressBookStateList.size() - 1`, pointing to the latest address book state, then there are no undone AddressBook states to restore. The `redo` command uses `Model#canRedoAddressBook()` to check if this is the case. If so, it will return an error to the user rather than attempting to perform the redo.
 
 </box>
 
 Step 5. The user then decides to execute the command `list`. Commands that do not modify the address book, such as `list`, will usually not call `Model#commitAddressBook()`, `Model#undoAddressBook()` or `Model#redoAddressBook()`. Thus, the `addressBookStateList` remains unchanged.
 
-![UndoRedoState4](images/UndoRedoState4.png)
+<puml src="diagrams/UndoRedoState4.puml" alt="UndoRedoState4" />
 
 Step 6. The user executes `clear`, which calls `Model#commitAddressBook()`. Since the `currentStatePointer` is not pointing at the end of the `addressBookStateList`, all address book states after the `currentStatePointer` will be purged. Reason: It no longer makes sense to redo the `add n/David …` command. This is the behavior that most modern desktop applications follow.
 
-![UndoRedoState5](images/UndoRedoState5.png)
+<puml src="diagrams/UndoRedoState5.puml" alt="UndoRedoState5" />
 
 The following activity diagram summarizes what happens when a user executes a new command:
 
@@ -348,7 +341,7 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
 
 Given below are instructions to test the app manually.
 
-<box type="info" light>
+<box type="info" seamless>
 
 **Note:** These instructions only provide a starting point for testers to work on;
 testers are expected to do more *exploratory* testing.

diff --git a/docs/Documentation.md b/docs/Documentation.md
@@ -1,104 +1,21 @@
-<frontmatter>
+---
  layout: default.md
  title: "Documentation guide"
  pageNav: 3
- pageNavTitle: "Table Of Content"
-</frontmatter>
+---
 
-# Documentation guide
-
-**Setting up and maintaining the project website:**
+# Documentation Guide
 
 * We use [**MarkBind**](https://markbind.org/) to manage documentation.
-* The `docs/` folder is contains the source files for the documentation website.
-* To learn how set it up and maintain the project website, follow the [_**MarkBind User Guide**_](https://markbind.org/userGuide/gettingStarted.html).
-
-
-<panel header="##### Quick Start :rocket:" expanded>
-
-++**Introduction**++
-
-<div class="indented">
-
-[**MarkBind**](https://markbind.org/) is a tool for generating static websites from markdown-like text, particularly suitable for text-heavy websites such as software project documentation.
-</div>
-
-++**Prerequisites**++
-
-<div class="indented">
-
- * a basic knowledge of [Markdown](https://www.markdownguide.org/basic-syntax/) and [HTML](https://www.w3schools.com/html/) syntax<br>
- * a basic knowledge of running CLI commands<br>
-</div>
-
-++**Installation**++
-
-<div class="indented">
-
- * install Java 8 or higher
- * install [Node.js](https://nodejs.org) 16 or higher
- * install [Graphviz](https://graphviz.org/download/) (for generating diagrams)
- * For Mac, you can use [Homebrew](https://brew.sh/) to install Graphviz: `brew install graphviz`
- * For Windows, you can use [Chocolatey](https://chocolatey.org/install) to install Graphviz: `choco install graphviz`
- * For Linux, you can use your package manager to install Graphviz: `sudo apt install graphviz`
- * open the project and go to the docs folder: `cd docs`
- * install dependencies, only needed once when setting up the project: `npm ci`
-</div>
-
-
-++**Updating Documents**++
-
-<div class="indented">
-
- <box type="info" light>
-
- MarkBind is a superset of Markdown. Refer the [MarkBind user guide](https://markbind.org/userGuide/gettingStarted.html) for more details.
- </box>
-
- **First, start the _live preview_**: Unless it is a trivial change, you would want to see how your change to the documentation source files will reflect in the generated website. You can use the MarkBind _live preview_ mode to preview the generated website as you update the source file. To start the live preview mode,
- 1. Open a command prompt.
- 1. Navigate to the the _documentation root_ (in most projects, the documentation root is `[project root]/docs` -- if you are not sure, look for the folder containing the `site.json` file).
- 1. Run the `npm run serve` command. That will open the generated website in your default browser.
- 1. In the browser, navigate to the page you want to modify.
-
- **Next, edit the files you want**:
- 1. Edit the source files (usually, `.md` files).
- 1. When you save the file, the live preview will update to reflect the new contents (after a few seconds).
-
- <box type="warning" seamless>
-
- While _live preview_ can pick up most changes, it may not be able to pick up certain changes (e.g., changes to files in the `_markbind` folder or changes to nunjucks macros). Furthermore, some syntax errors in your code can cause the live preview to crash. In those cases, just stop the server (<kbd>Ctrl</kbd>+<kbd>C</kbd> on Windows) and start it again.
- </box>
-
-</div>
-
-++**Automating Deployments**++
-
-<div class="indented">
-
- The docs site can be deployed automatically with GitHub Actions. The `.github/workflows/docs.yml` file provides a ready made script to achieve it. More info [here](https://markbind.org/userGuide/deployingTheSite.html#deploying-via-github-actions).
-</div>
-
-</panel>
-
-* Note these points when adapting the documentation to a different project/product:
- * The [_markbind/tweaking the page structure_](https://markbind.org/userGuide/tweakingThePageStructure.html) and [_markbind/site.json_](https://markbind.org/userGuide/siteJsonFile.html) pages have information on how to update site-wide elements such as the top navigation bar.
- * :bulb: In addition to updating content files, you might have to update the config files `docs\site.json` and the layout files `docs\_markbind\layouts\default.md` (which contains a reference to `AB-3` that comes into play when converting documentation pages to PDF format).
-* If you are using Intellij for editing documentation files, you can consider enabling 'soft wrapping' for `*.md` files, as explained in [_se-edu/guides **Intellij IDEA: Useful settings**_](https://se-education.org/guides/tutorials/intellijUsefulSettings.html#enabling-soft-wrapping)
-
+* The `docs/` folder contains the source files for the documentation website.
+* To learn how set it up and maintain the project website, follow the guide [[se-edu/guides] Working with Forked MarkBind sites](https://se-education.org/guides/tutorials/markbind-forked-sites.html) for project documentation.
 
 **Style guidance:**
 
 * Follow the [**_Google developer documentation style guide_**](https://developers.google.com/style).
+* Also relevant is the [_se-edu/guides **Markdown coding standard**_](https://se-education.org/guides/conventions/markdown.html).
 
-* Also relevant is the [_se-edu/guides **Markdown coding standard**_](https://se-education.org/guides/conventions/markdown.html)
-
-**Diagrams:**
-
-* See the [_markbind/user-guide/diagrams **Using PlantUML with MarkBind**_](https://markbind.org/userGuide/components/imagesAndDiagrams.html#diagrams)
-
-* See the [_se-edu/guides **Using PlantUML**_](https://se-education.org/guides/tutorials/plantUml.html)
 
-**Converting a document to the PDF format:**
+**Converting to PDF**
 
-* See the guide [_se-edu/guides **Saving web documents as PDF files**_](https://se-education.org/guides/tutorials/savingPdf.html)
+* See the guide [_se-edu/guides **Saving web documents as PDF files**_](https://se-education.org/guides/tutorials/savingPdf.html).
diff --git a/docs/Logging.md b/docs/Logging.md
@@ -1,7 +1,7 @@
-<frontmatter>
+---
  layout: default.md
  title: "Logging guide"
-</frontmatter>
+---
 
 # Logging guide
 

diff --git a/docs/SettingUp.md b/docs/SettingUp.md
@@ -1,9 +1,8 @@
-<frontmatter>
+---
  layout: default.md
  title: "Setting up and getting started"
  pageNav: 3
- pageNavTitle: "Table Of Content"
-</frontmatter>
+---
 
 # Setting up and getting started
 
@@ -14,7 +13,7 @@
 
 ## Setting up the project in your computer
 
-<box type="warning" light>
+<box type="warning" seamless>
 
 **Caution:**
 Follow the steps in the following guide precisely. Things will not work out if you deviate in some steps.
@@ -24,8 +23,10 @@ First, **fork** this repo, and **clone** the fork into your computer.
 
 If you plan to use Intellij IDEA (highly recommended):
 1. **Configure the JDK**: Follow the guide [_[se-edu/guides] IDEA: Configuring the JDK_](https://se-education.org/guides/tutorials/intellijJdk.html) to to ensure Intellij is configured to use **JDK 11**.
-1. **Import the project as a Gradle project**: Follow the guide [_[se-edu/guides] IDEA: Importing a Gradle project_](https://se-education.org/guides/tutorials/intellijImportGradleProject.html) to import the project into IDEA.<br>
- :exclamation: Note: Importing a Gradle project is slightly different from importing a normal Java project.
+1. **Import the project as a Gradle project**: Follow the guide [_[se-edu/guides] IDEA: Importing a Gradle project_](https://se-education.org/guides/tutorials/intellijImportGradleProject.html) to import the project into IDEA.
+ <box type="warning" seamless>
+ Note: Importing a Gradle project is slightly different from importing a normal Java project.
+ </box>
 1. **Verify the setup**:
  1. Run the `seedu.address.Main` and try a few commands.
  1. [Run the tests](Testing.md) to ensure they all pass.
@@ -38,8 +39,8 @@ If you plan to use Intellij IDEA (highly recommended):
 
  If using IDEA, follow the guide [_[se-edu/guides] IDEA: Configuring the code style_](https://se-education.org/guides/tutorials/intellijCodeStyle.html) to set up IDEA's coding style to match ours.
 
- <box type="tip" light>
- 
+ <box type="tip" seamless>
+
  **Tip:**
  Optionally, you can follow the guide [_[se-edu/guides] Using Checkstyle_](https://se-education.org/guides/tutorials/checkstyle.html) to find how to use the CheckStyle within IDEA e.g., to report problems _as_ you write code.
  </box>

diff --git a/docs/Testing.md b/docs/Testing.md
@@ -1,9 +1,8 @@
-<frontmatter>
+---
  layout: default.md
  title: "Testing guide"
  pageNav: 3
- pageNavTitle: "Table Of Content"
-</frontmatter>
+---
 
 # Testing guide
 
@@ -23,7 +22,7 @@ There are two ways to run tests.
 * **Method 2: Using Gradle**
  * Open a console and run the command `gradlew clean test` (Mac/Linux: `./gradlew clean test`)
 
-<box type="info" light>
+<box type="info" seamless>
 
 **Link**: Read [this Gradle Tutorial from the se-edu/guides](https://se-education.org/guides/tutorials/gradle.html) to learn more about using Gradle.
 </box>