Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Switch docs to markbind #1

Merged
merged 4 commits into from
Feb 13, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
name: MarkBind Action

on:
push:
branches:
- master

jobs:
build_and_deploy:
runs-on: ubuntu-latest
steps:
- name: Install Graphviz
run: sudo apt-get install graphviz
- name: Install Java
uses: actions/setup-java@v3
with:
java-version: '11'
distribution: 'temurin'
- name: Build & Deploy MarkBind site
uses: MarkBind/markbind-action@v2
with:
token: ${{ secrets.GITHUB_TOKEN }}
rootDirectory: './docs'
baseUrl: '/tp' # assuming your repo name is tp
version: '^5.2.0'
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,4 @@ src/test/data/sandbox/
# MacOS custom attributes files created by Finder
.DS_Store
docs/_site/
docs/_markbind/logs/
23 changes: 23 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
_markbind/logs/

# Dependency directories
node_modules/

# Production build files (change if you output the build to a different directory)
_site/

# Env
.env
.env.local

# IDE configs
.vscode/
.idea/*
*.iml
6 changes: 4 additions & 2 deletions docs/AboutUs.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
---
layout: page
title: About Us
layout: default.md
title: "About Us"
---

# About Us

We are a team based in the [School of Computing, National University of Singapore](http://www.comp.nus.edu.sg).

You can reach us at the email `seer[at]comp.nus.edu.sg`
Expand Down
6 changes: 4 additions & 2 deletions docs/Configuration.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
layout: page
title: Configuration guide
layout: default.md
title: "Configuration guide"
---

# Configuration guide

Certain properties of the application can be controlled (e.g user preferences file location, logging level) through the configuration file (default: `config.json`).
13 changes: 8 additions & 5 deletions docs/DevOps.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
---
layout: page
title: DevOps guide
layout: default.md
title: "DevOps guide"
pageNav: 3
---

* Table of Contents
{:toc}
# DevOps guide

--------------------------------------------------------------------------------------------------------------------
<!-- * Table of Contents -->
<page-nav-print />

<!-- -------------------------------------------------------------------------------------------------------------------- -->

## Build automation

Expand Down
116 changes: 65 additions & 51 deletions docs/DeveloperGuide.md

Large diffs are not rendered by default.

28 changes: 10 additions & 18 deletions docs/Documentation.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,21 @@
---
layout: page
title: Documentation guide
layout: default.md
title: "Documentation guide"
pageNav: 3
---

**Setting up and maintaining the project website:**

* We use [**Jekyll**](https://jekyllrb.com/) to manage documentation.
* The `docs/` folder is used for documentation.
* To learn how set it up and maintain the project website, follow the guide [_[se-edu/guides] **Using Jekyll for project documentation**_](https://se-education.org/guides/tutorials/jekyll.html).
* Note these points when adapting the documentation to a different project/product:
* The 'Site-wide settings' section of the page linked above has 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\_config.yml` and `docs\_sass\minima\_base.scss` (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)
# Documentation Guide

* We use [**MarkBind**](https://markbind.org/) to manage documentation.
* 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 [_[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).
10 changes: 0 additions & 10 deletions docs/Gemfile

This file was deleted.

6 changes: 4 additions & 2 deletions docs/Logging.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
---
layout: page
title: Logging guide
layout: default.md
title: "Logging guide"
---

# Logging guide

* We are using `java.util.logging` package for logging.
* The `LogsCenter` class is used to manage the logging levels and logging destinations.
* The `Logger` for a class can be obtained using `LogsCenter.getLogger(Class)` which will log messages according to the specified logging level.
Expand Down
26 changes: 16 additions & 10 deletions docs/SettingUp.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,32 @@
---
layout: page
title: Setting up and getting started
layout: default.md
title: "Setting up and getting started"
pageNav: 3
---

* Table of Contents
{:toc}
# Setting up and getting started

<!-- * Table of Contents -->
<page-nav-print />

--------------------------------------------------------------------------------------------------------------------

## Setting up the project in your computer

<div markdown="span" class="alert alert-warning">:exclamation: **Caution:**
<box type="warning" seamless>

**Caution:**
Follow the steps in the following guide precisely. Things will not work out if you deviate in some steps.
</div>
</box>

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.
Expand All @@ -34,10 +39,11 @@ 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.

<div markdown="span" class="alert alert-primary">:bulb: **Tip:**
<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.
</div>
</box>

1. **Set up CI**

Expand Down
19 changes: 12 additions & 7 deletions docs/Testing.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
---
layout: page
title: Testing guide
layout: default.md
title: "Testing guide"
pageNav: 3
---

* Table of Contents
{:toc}
# Testing guide

--------------------------------------------------------------------------------------------------------------------
<!-- * Table of Contents -->
<page-nav-print />

<!-- -------------------------------------------------------------------------------------------------------------------- -->

## Running tests

Expand All @@ -19,8 +22,10 @@ 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`)

<div markdown="span" class="alert alert-secondary">:link: **Link**: Read [this Gradle Tutorial from the se-edu/guides](https://se-education.org/guides/tutorials/gradle.html) to learn more about using Gradle.
</div>
<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>

--------------------------------------------------------------------------------------------------------------------

Expand Down
52 changes: 29 additions & 23 deletions docs/UserGuide.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
---
layout: page
title: User Guide
layout: default.md
title: "User Guide"
pageNav: 3
---

AddressBook Level 3 (AB3) is a **desktop app for managing contacts, optimized for use via a Command Line Interface** (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, AB3 can get your contact management tasks done faster than traditional GUI apps.
# AB-3 User Guide

* Table of Contents
{:toc}
AddressBook Level 3 (AB3) is a **desktop app for managing contacts, optimized for use via a Line Interface** (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, AB3 can get your contact management tasks done faster than traditional GUI apps.

<!-- * Table of Contents -->
<page-nav-print />

--------------------------------------------------------------------------------------------------------------------

Expand Down Expand Up @@ -41,9 +44,9 @@ AddressBook Level 3 (AB3) is a **desktop app for managing contacts, optimized fo

## Features

<div markdown="block" class="alert alert-info">
<box type="info" seamless>

**:information_source: Notes about the command format:**<br>
**Notes about the command format:**<br>

* Words in `UPPER_CASE` are the parameters to be supplied by the user.<br>
e.g. in `add n/NAME`, `NAME` is a parameter which can be used as `add n/John Doe`.
Expand All @@ -61,7 +64,7 @@ AddressBook Level 3 (AB3) is a **desktop app for managing contacts, optimized fo
e.g. if the command specifies `help 123`, it will be interpreted as `help`.

* If you are using a PDF version of this document, be careful when copying and pasting commands that span multiple lines as space characters surrounding line-breaks may be omitted when copied over to the application.
</div>
</box>

### Viewing help : `help`

Expand All @@ -78,9 +81,10 @@ Adds a person to the address book.

Format: `add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…​`

<div markdown="span" class="alert alert-primary">:bulb: **Tip:**
A person can have any number of tags (including 0)
</div>
<box type="tip" seamless>

**Tip:** A person can have any number of tags (including 0)
</box>

Examples:
* `add n/John Doe p/98765432 e/[email protected] a/John street, block 123, #01-01`
Expand Down Expand Up @@ -161,10 +165,12 @@ 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.

<div markdown="span" class="alert alert-warning">:exclamation: **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.<br>
Furthermore, certain edits can cause the AddressBook to behave in unexpected ways (e.g., if a value entered is outside of the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly.
</div>
<box type="warning" seamless>

**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.<br>
Furthermore, certain edits can cause the AddressBook to behave in unexpected ways (e.g., if a value entered is outside the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly.
</box>

### Archiving data files `[coming in v2.0]`

Expand All @@ -187,12 +193,12 @@ _Details coming soon ..._

## Command summary

Action | Format, Examples
--------|------------------
**Add** | `add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…​` <br> e.g., `add n/James Ho p/22224444 e/[email protected] a/123, Clementi Rd, 1234665 t/friend t/colleague`
**Clear** | `clear`
Action | Format, Examples
-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------
**Add** | `add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…​` <br> e.g., `add n/James Ho p/22224444 e/[email protected] a/123, Clementi Rd, 1234665 t/friend t/colleague`
**Clear** | `clear`
**Delete** | `delete INDEX`<br> e.g., `delete 3`
**Edit** | `edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [t/TAG]…​`<br> e.g.,`edit 2 n/James Lee e/[email protected]`
**Find** | `find KEYWORD [MORE_KEYWORDS]`<br> e.g., `find James Jake`
**List** | `list`
**Help** | `help`
**Edit** | `edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [t/TAG]…​`<br> e.g.,`edit 2 n/James Lee e/[email protected]`
**Find** | `find KEYWORD [MORE_KEYWORDS]`<br> e.g., `find James Jake`
**List** | `list`
**Help** | `help`
15 changes: 0 additions & 15 deletions docs/_config.yml

This file was deleted.

23 changes: 0 additions & 23 deletions docs/_data/projects.yml

This file was deleted.

6 changes: 0 additions & 6 deletions docs/_includes/custom-head.html

This file was deleted.

Loading
Loading