From d39eadb589e669026981b69b662ea6f3319da432 Mon Sep 17 00:00:00 2001 From: damithc Date: Mon, 11 Sep 2023 22:56:12 +0800 Subject: [PATCH] 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 --- .gitignore | 1 + docs/.gitignore | 2 +- docs/AboutUs.md | 4 +- docs/Configuration.md | 4 +- docs/DevOps.md | 5 +- docs/DeveloperGuide.md | 41 ++++---- docs/Documentation.md | 99 ++----------------- docs/Logging.md | 4 +- docs/SettingUp.md | 17 ++-- docs/Testing.md | 7 +- docs/UserGuide.md | 11 +-- docs/_markbind/layouts/default.md | 2 +- docs/_markbind/variables.json | 2 +- docs/_markbind/variables.md | 2 +- docs/diagrams/adding/ParserClass.puml | 14 +++ docs/diagrams/adding/RemarkClass.puml | 19 ++++ docs/images/ArchitectureDiagram.png | Bin 19887 -> 0 bytes docs/images/ArchitectureSequenceDiagram.png | Bin 15175 -> 0 bytes docs/images/BetterModelClassDiagram.png | Bin 14116 -> 0 bytes docs/images/CommitActivityDiagram.png | Bin 16227 -> 0 bytes docs/images/ComponentManagers.png | Bin 17411 -> 0 bytes docs/images/DeleteSequenceDiagram.png | Bin 28536 -> 0 bytes docs/images/LogicClassDiagram.png | Bin 36640 -> 0 bytes docs/images/LogicStorageDIP.png | Bin 5808 -> 0 bytes docs/images/ModelClassDiagram.png | Bin 27204 -> 0 bytes docs/images/ParserClasses.png | Bin 29478 -> 0 bytes docs/images/StorageClassDiagram.png | Bin 29426 -> 0 bytes docs/images/UiClassDiagram.png | Bin 48363 -> 0 bytes docs/images/UndoRedoState0.png | Bin 6619 -> 0 bytes docs/images/UndoRedoState1.png | Bin 7454 -> 0 bytes docs/images/UndoRedoState2.png | Bin 7855 -> 0 bytes docs/images/UndoRedoState3.png | Bin 7588 -> 0 bytes docs/images/UndoRedoState4.png | Bin 7605 -> 0 bytes docs/images/UndoRedoState5.png | Bin 9427 -> 0 bytes docs/images/UndoSequenceDiagram.png | Bin 27508 -> 0 bytes docs/images/add-remark/CommandInterface.png | Bin 16826 -> 0 bytes docs/images/add-remark/ParserInterface.png | Bin 6995 -> 0 bytes docs/images/tracing/LogicSequenceDiagram.png | Bin 16688 -> 0 bytes docs/index.md | 4 +- docs/package-lock.json | 62 ++++++------ docs/package.json | 4 +- docs/team/johndoe.md | 4 +- docs/tutorials/AddRemark.md | 17 ++-- docs/tutorials/RemovingFields.md | 7 +- docs/tutorials/TracingCode.md | 21 ++-- 45 files changed, 146 insertions(+), 207 deletions(-) create mode 100644 docs/diagrams/adding/ParserClass.puml create mode 100644 docs/diagrams/adding/RemarkClass.puml delete mode 100644 docs/images/ArchitectureDiagram.png delete mode 100644 docs/images/ArchitectureSequenceDiagram.png delete mode 100644 docs/images/BetterModelClassDiagram.png delete mode 100644 docs/images/CommitActivityDiagram.png delete mode 100644 docs/images/ComponentManagers.png delete mode 100644 docs/images/DeleteSequenceDiagram.png delete mode 100644 docs/images/LogicClassDiagram.png delete mode 100644 docs/images/LogicStorageDIP.png delete mode 100644 docs/images/ModelClassDiagram.png delete mode 100644 docs/images/ParserClasses.png delete mode 100644 docs/images/StorageClassDiagram.png delete mode 100644 docs/images/UiClassDiagram.png delete mode 100644 docs/images/UndoRedoState0.png delete mode 100644 docs/images/UndoRedoState1.png delete mode 100644 docs/images/UndoRedoState2.png delete mode 100644 docs/images/UndoRedoState3.png delete mode 100644 docs/images/UndoRedoState4.png delete mode 100644 docs/images/UndoRedoState5.png delete mode 100644 docs/images/UndoSequenceDiagram.png delete mode 100644 docs/images/add-remark/CommandInterface.png delete mode 100644 docs/images/add-remark/ParserInterface.png delete mode 100644 docs/images/tracing/LogicSequenceDiagram.png diff --git a/.gitignore b/.gitignore index 284c4ca7c..eab4c7db6 100644 --- 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 index e69446a03..1748e487f 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -20,4 +20,4 @@ _site/ # IDE configs .vscode/ .idea/* -*.iml \ No newline at end of file +*.iml diff --git a/docs/AboutUs.md b/docs/AboutUs.md index 7c1ea2248..8cf4ab68e 100644 --- a/docs/AboutUs.md +++ b/docs/AboutUs.md @@ -1,7 +1,7 @@ - +--- layout: default.md title: "About Us" - +--- # About Us diff --git a/docs/Configuration.md b/docs/Configuration.md index 35eaa1589..32f6255f3 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -1,7 +1,7 @@ - +--- layout: default.md title: "Configuration guide" - +--- # Configuration guide diff --git a/docs/DevOps.md b/docs/DevOps.md index 37925ead4..8228c845e 100644 --- a/docs/DevOps.md +++ b/docs/DevOps.md @@ -1,9 +1,8 @@ - +--- layout: default.md title: "DevOps guide" pageNav: 3 - pageNavTitle: "Table Of Content" - +--- # DevOps guide diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index 710fbc733..a5a11185a 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -1,9 +1,8 @@ - +--- layout: default.md title: "Developer Guide" pageNav: 3 - pageNavTitle: "Table Of Content" - +--- # 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** - - -**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. - - ### Architecture @@ -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) + - + **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. @@ -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) - + **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.
@@ -180,17 +173,17 @@ 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) + 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) + 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) + - + **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`. @@ -198,10 +191,10 @@ Step 3. The user executes `add n/David …​` to add a new person. The `add` co 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) + - + **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,7 +205,7 @@ The following sequence diagram shows how the undo operation works: - + **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. @@ -220,7 +213,7 @@ The following sequence diagram shows how the undo operation works: 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. - + **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. @@ -228,11 +221,11 @@ The `redo` command does the opposite — it calls `Model#redoAddressBook()`, 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) + 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) + 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. - + **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 index 12d7de90e..082e652d9 100644 --- a/docs/Documentation.md +++ b/docs/Documentation.md @@ -1,104 +1,21 @@ - +--- layout: default.md title: "Documentation guide" pageNav: 3 - pageNavTitle: "Table Of Content" - +--- -# 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). - - - - -++**Introduction**++ - -
- -[**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. -
- -++**Prerequisites**++ - -
- - * a basic knowledge of [Markdown](https://www.markdownguide.org/basic-syntax/) and [HTML](https://www.w3schools.com/html/) syntax
- * a basic knowledge of running CLI commands
-
- -++**Installation**++ - -
- - * 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` -
- - -++**Updating Documents**++ - -
- - - - MarkBind is a superset of Markdown. Refer the [MarkBind user guide](https://markbind.org/userGuide/gettingStarted.html) for more details. - - - **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). - - - - 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 (Ctrl+C on Windows) and start it again. - - -
- -++**Automating Deployments**++ - -
- - 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). -
- - - -* 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 index e6fdc6051..589644ad5 100644 --- a/docs/Logging.md +++ b/docs/Logging.md @@ -1,7 +1,7 @@ - +--- layout: default.md title: "Logging guide" - +--- # Logging guide diff --git a/docs/SettingUp.md b/docs/SettingUp.md index 45f66f3f6..03df0295b 100644 --- a/docs/SettingUp.md +++ b/docs/SettingUp.md @@ -1,9 +1,8 @@ - +--- layout: default.md title: "Setting up and getting started" pageNav: 3 - pageNavTitle: "Table Of Content" - +--- # Setting up and getting started @@ -14,7 +13,7 @@ ## Setting up the project in your computer - + **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.
- :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. + + Note: Importing a Gradle project is slightly different from importing a normal Java project. + 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. - - + + **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. diff --git a/docs/Testing.md b/docs/Testing.md index 83d76f980..78ddc57e6 100644 --- a/docs/Testing.md +++ b/docs/Testing.md @@ -1,9 +1,8 @@ - +--- layout: default.md title: "Testing guide" pageNav: 3 - pageNavTitle: "Table Of Content" - +--- # 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`) - + **Link**: Read [this Gradle Tutorial from the se-edu/guides](https://se-education.org/guides/tutorials/gradle.html) to learn more about using Gradle. diff --git a/docs/UserGuide.md b/docs/UserGuide.md index e97195773..b3abf0e87 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -1,9 +1,8 @@ - +--- layout: default.md title: "User Guide" pageNav: 3 - pageNavTitle: "Table Of Content" - +--- # AB-3 User Guide @@ -45,7 +44,7 @@ AddressBook Level 3 (AB3) is a **desktop app for managing contacts, optimized fo ## Features - + **Notes about the command format:**
@@ -82,7 +81,7 @@ Adds a person to the address book. Format: `add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…​` - + **Tip:** A person can have any number of tags (including 0) @@ -166,7 +165,7 @@ AddressBook data are saved in the hard disk automatically after any command that AddressBook data are saved automatically as a JSON file `[JAR file location]/data/addressbook.json`. Advanced users are welcome to update data directly by editing that data file. - + **Caution:** If your changes to the data file makes its format invalid, AddressBook will discard all data and start with an empty data file at the next run. Hence, it is recommended to take a backup of the file before editing it. diff --git a/docs/_markbind/layouts/default.md b/docs/_markbind/layouts/default.md index f4e2377bb..7348aace9 100644 --- a/docs/_markbind/layouts/default.md +++ b/docs/_markbind/layouts/default.md @@ -21,7 +21,7 @@