Skip to content

Commit

Permalink
Update UserGuide.adoc with "Managing Slots" and diagrams (#119)
Browse files Browse the repository at this point in the history 
* v1.1

* fix some errors and typos

* Refactor entire project, remove all traces of Addressbook

* Update developer guide for ExportCommandP (#80)

* Update documentation for view command (#81)

* Remove remaining Addressbook classes

* Refactor some classes

* fix missing files issue

* Add test cases for add function, Utils and other code enhancements

* fix codacy issues

* fix codacy issues

* Add tests for Utils

* Add diagrams

* Update Ui.png

* fix issue with Ui.png

* Update Codacy Badge link due to reinitialization.

* Enhance ordering of slots printed

* Update UserGuide.adoc with feedback from peers

* Update UserGuide.adoc with nicer tables

* Update UserGuide.adoc: fix formatting issues

* UserGuide.adoc Remove potential Netlify breaking code

* README.adoc revert changes

* UserGuide.adoc revert Netlify breakdown test code

* Update UserGuide.adoc with Managing Slots and diagrams

* Solved unchecked or unsafe operation warnings
  • Loading branch information
@seanieyap @marcus-pzj
seanieyap authored and marcus-pzj committed Mar 25, 2019
1 parent 484ba2d commit b99339b
Show file tree
Hide file tree
Showing 49 changed files with 1,472 additions and 371 deletions.
757 changes: 388 additions & 369 deletions docs/DeveloperGuide.adoc
View file

Large diffs are not rendered by default.

3 changes: 3 additions & 0 deletions docs/HelpWindow.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
:no-site-header:

include::UserGuide.adoc[]
85 changes: 85 additions & 0 deletions docs/UsingAppVeyor.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
= AppVeyor
:site-section: DeveloperGuide
:imagesDir: images
:stylesDir: stylesheets

https://www.appveyor.com/[AppVeyor] is a _Continuous Integration_ platform for GitHub projects. It runs its builds on Windows virtual machines.

AppVeyor can run the project's tests automatically whenever new code is pushed to the repo. This ensures that existing functionality and features have not been broken on Windows by the changes.

The current AppVeyor setup runs `gradlew.bat headless allTests` whenever someone pushes code to the repo.

If you would like to customize your AppVeyor build further, you can learn more about AppVeyor from the https://www.appveyor.com/docs/[AppVeyor Documentation].

== Setting up AppVeyor

. Fork the repo to your own organization.
. Go to https://ci.appveyor.com/, and under `Login`, click on `GitHub` to login with your GitHub account. Enter your GitHub account details if needed.
+
image:appveyor/login.png[Click on GitHub in the login page]
+
. After logging in, you will be brought to your projects dashboard. Click on `NEW PROJECT`.
+
image:appveyor/add-project-1.png[Click on "NEW PROJECT" in the projects dashboard]
+
. You will be brought to the `Select repository` page. Select `GitHub`.
* On your first usage of AppVeyor, you will need to give AppVeyor authorization to your GitHub account. Click on `Authorize GitHub`.
+
image:appveyor/add-project-2.png[Click on Authorize GitHub]
+
* This will bring you to a GitHub page that manages the access of third-party applications to your repositories.
+
Depending on whether you are the owner of the repository, you can either
grant access:
+
image:grant_access.png[Grant Access]
+
Or request access:
+
image:request_access.png[Request Access]
+
. AppVeyor will then list the repositories you have access to in your GitHub account. Find the repository you want to set AppVeyor up on, and then click `ADD`.
+
image:appveyor/add-project-3.png[Click "Add" on the repository you want to set AppVeyor up on]
+
. AppVeyor will then be activated on that repository. To see the CI in action, push a commit to any branch!
* Go to the repository and see the pushed commit. There should be an icon which will link you to the AppVeyor build:
+
image:appveyor/ci-pending.png[Commit build]
+
* As the build is run on a remote machine, we can only examine the logs it produces:
+
image:appveyor/ci-log.png[AppVeyor build]
+
. Update the link to the "build status" badge at the top of `README.adoc` to point to the AppVeyor build status of your own repo.
* To find your build status badge URL, first go to your project settings by clicking on the "Settings" icon:
+
image:appveyor/project-settings-1.png[Click on project settings]
+
* Then go to the `Badges` section of your project settings by clicking on it:
+
image:appveyor/project-settings-2.png[Click on "Badges"]
+
* As AppVeyor does not provide asciidoc code for the badge, we will have to create our own. Start by copying the markdown code provided:
+
image:appveyor/project-settings-3.png[Copy the markdown code]
+
The markdown code should be in this format:
+
----
[![Build status](<link to image>)](<link to project>)
----
+
Convert it to the asciidoc format as follows:
+
----
<link to project>[image:<link to image>[Build status]]
----
+
The asciidoc code should look similar to:
+
----
https://ci.appveyor.com/project/damithc/addressbook-level4[image:https://ci.appveyor.com/api/projects/status/3boko2x2vr5cc3w2?svg=true[Build status]]
----
+
Copy and paste the asciidoc code to your `README.adoc` file.
42 changes: 42 additions & 0 deletions docs/UsingCheckstyle.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
= Using Checkstyle-IDEA
:site-section: DeveloperGuide
:imagesDir: images
:stylesDir: stylesheets
:experimental:
ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
endif::[]

== Configuring Checkstyle-IDEA

. Install the Checkstyle-IDEA plugin by going to `File` > `Settings` (Windows/Linux), or `IntelliJ IDEA` > `Preferences...` (macOS). +
Select `Plugins`, press `Browse Repository`, and find the plugin. +
Restart the IDE to complete the installation.
. Click `File` > `Settings...` > `Other Settings` > `Checkstyle`
. Set `Scan Scope` to `Only Java sources (including tests)`, so that the plugin will run checkstyle for our test source codes as well
. Ensure that the `Checkstyle version` is set to `8.1`. This is the same version that we are using inside Gradle, so that you won't get any errors due to version incompatibility
* If `Checkstyle version` is not set to `8.1`, set it to version `8.1` and click `Apply`
+
image::checkstyle-idea-scan-scope.png[width="500"]
. Click the plus sign under `Configuration File`
. Enter an arbitrary description e.g. addressbook
. Select `Use a local Checkstyle file`
. Use the checkstyle configuration file found at `config/checkstyle/checkstyle.xml`
. Click `Next` > `Finish`
. Mark `Active` for the newly imported check configuration
+
image::checkstyle-idea-configuration.png[width="700"]
. Click `OK`

== Troubleshooting Checkstyle-IDEA

**Problem: When importing `checkstyle.xml`, Checkstyle-IDEA plugin complains that `The Checkstyle rules file could not be parsed. ... The file has been blacklisted for 60s.`**

* Reason: `checkstyle.xml` is written for a particular version, but the plugin was not configured to the correct version.
* Solution: Ensure that you have selected the correct `Checkstyle version` that matches the version in `build.gradle` and have clicked `Apply`, as `checkstyle.xml` is written for Gradle's checkstyle.

**Problem: After setting up `checkstyle.xml`, Checkstyle-IDEA plugin does not seem to highlight the errors / real-time scanning seems broken.**

* Reason: The plugin may not immediately run after setting it up.
* Solution: Restart the IDE.
54 changes: 54 additions & 0 deletions docs/UsingCoveralls.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
= Using Coveralls
:site-section: DeveloperGuide
:imagesDir: images
:stylesDir: stylesheets

https://coveralls.io/[Coveralls] is a web service that tracks code coverage over time for GitHub projects.
Coveralls requires Travis CI to be set up beforehand as Travis sends the coverage report from the latest build to Coveralls.
If you have not set up Travis CI, see <<UsingTravis#, UsingTravis.adoc>>. Currently, Coveralls supports Travis CI but not AppVeyor.

== Setting up Coveralls

. Go to https://coveralls.io/ and click `SIGN IN`. Then click `GITHUB SIGN IN` and enter your GitHub account details if needed.
+
. After logging in, you will be brought to the `Your Repositories` page. On the site's navigation bar, click https://coveralls.io/repos/new[ADD REPOS].
+
. Find the switch for the forked repository.
* If the organization is not shown, click `GITHUB SETTINGS` as shown below:
+
image:coveralls/github_settings.png[GitHub settings]
+
This should bring you to a GitHub page that manages the access of third-party applications. Depending on whether you are the owner of the repository, you can either grant access
+
image:grant_access.png[Grant Access]
+
or request access
+
image:request_access.png[Request Access]
+
to Coveralls so that it can access your repository.
* If your repository cannot be found, click `SYNC REPOS`.
+
image:coveralls/sync_repos.png[Sync repos]
+
. Activate the switch.
+
image:coveralls/flick_repository_switch.png[Activate the switch]
+
. Update the link of the `Coverage Status` badge at the top of your <<README#, README.adoc>> to point to that of your own repo by replacing the outlined areas with `your-org-name/your-repo-name`.
+
image:coveralls/coverage_asciidoc_code.png[Coverage Status Badge]
+
. You can now see the coverage report for your project after each Travis build by clicking on the `Coverage Status` badge.
+
image:coveralls/coverage_report.png[Coverage Report Summary]

== Disabling Coveralls Automatic Comments on Pull Requests

Coveralls automatically comments on the coverage status of the pull requests in GitHub. If it's a hindrance, you can disable it in the settings of your project in Coveralls:

. Click `Settings`.
+
. Uncheck the `LEAVE COMMENTS?` checkbox. Then click `SAVE CHANGES`.
+
image:coveralls/disable_comments.png[Disable comments, width = 942]
107 changes: 107 additions & 0 deletions docs/UsingGradle.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
= Using Gradle
:site-section: DeveloperGuide
:imagesDir: images
:stylesDir: stylesheets
:experimental:
ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
endif::[]

https://gradle.org/[Gradle] is a build automation tool. It can automate build-related tasks such as

* Running tests
* Managing library dependencies
* Analyzing code for style compliance
The gradle configuration for this project is defined in the _build script_ link:../build.gradle[`build.gradle`].

[NOTE]
To learn more about gradle build scripts, refer https://docs.gradle.org/current/userguide/tutorial_using_tasks.html[Build Scripts Basics].

== Running Gradle Commands

To run a Gradle command, open a command window on the project folder and enter the Gradle command. Gradle commands look like this:

* On Windows: `gradlew <task1> <task2> ...` e.g. `gradlew clean allTests`
* On Mac/Linux: `./gradlew <task1> <task2>...` e.g.
`./gradlew clean allTests`

[NOTE]
If you do not specify any tasks, Gradlew will run the default tasks `clean` `headless` `allTests` `coverage`

== Cleaning the Project

* *`clean`* +
Deletes the files created during the previous build tasks (e.g. files in the `build` folder). e.g. `./gradlew clean`

[TIP]
*`clean` to force Gradle to execute a task*: +
When running a Gradle task, Gradle will try to figure out if the task needs running at all. If Gradle determines that the output of the task will be same as the previous time, it will not run the task. For example, it will not build the JAR file again if the relevant source files have not changed since the last time the JAR file was built. If we want to force Gradle to run a task, we can combine that task with `clean`. Once the build files have been `clean` ed, Gradle has no way to determine if the output will be same as before, so it will be forced to execute the task.

== Creating the JAR file

* *`shadowJar`* +
Creates the `addressbook.jar` file in the `build/jar` folder, _if the current file is outdated_. +
e.g. `./gradlew shadowJar`

****
To force Gradle to create the JAR file even if the current one is up-to-date, you can '`clean`' first. +
e.g. `./gradlew clean shadowJar`
****

[NOTE]
*Why do we create a fat JAR?* If we package only our own class files into the JAR file, it will not work properly unless the user has all the other JAR files (i.e. third party libraries) our classes depend on, which is rather inconvenient. Therefore, we package all dependencies into a single JAR files, creating what is also known as a _fat_ JAR file. To create a fat JAR file, we use the Gradle plugin https://github.com/johnrengelman/shadow[shadow jar].

== Rendering AsciiDoc files

* **`asciidoctor`** +
Converts AsciiDoc files in `docs` to HTML format. Generated HTML files can be found in `build/docs`.
* **`deployOfflineDocs`** +
Updates the offline user guide, and its associated files, used by the Help window in the application. Deployed HTML files and images can be found in `src/main/resources/docs`.

== Running the application

* *`run`* +
Builds and runs the application.
* *`runShadow`* +
Builds the application as a fat JAR, and then runs it.

== Running code style checks

* **`checkstyleMain`** +
Runs the code style check for the main code base
* **`checkstyleTest`** +
Runs the code style check for the test code base

The set of code style rules implemented can be found in `config/checkstyle/checkstyle.xml`. To enable _exceptions_ to code styles, add in the comment `//CODESTYLE.OFF: RuleName` at the start of the section and `//CODESTYLE.ON: RuleName` at the end of the section.

== Running Tests

* **`allTests`** +
Runs all tests.
* **`guiTests`** +
Runs all tests in the `seedu.address.ui` and `systemtests` package
* **`nonGuiTests`** +
Runs all non-GUI tests in the `seedu.address`
package
* **`headless`** +
Sets the test mode as _headless_. The mode is effective for that Gradle run only so it should be combined with other test tasks.

Here are some examples:

* `./gradlew headless allTests` -- Runs all tests in headless mode
* `./gradlew clean nonGuiTests` -- Cleans the project and runs non-GUI
tests

== Updating Dependencies

There is no need to run these Gradle tasks manually as they are called automatically by other relevant Gradle tasks.

* **`compileJava`** +
Checks whether the project has the required dependencies to compile and run the main program, and download any missing dependencies before compiling the classes. +
See `build.gradle` ->
`allprojects` -> `dependencies` -> `compile` for the list of dependencies required.
* **`compileTestJava`** +
Checks whether the project has the required dependencies to perform testing, and download any missing dependencies before compiling the test classes. +
See `build.gradle` -> `allprojects` -> `dependencies` -> `testCompile` for the list of dependencies required.
50 changes: 50 additions & 0 deletions docs/UsingNetlify.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
= Using Netlify
:site-section: DeveloperGuide
:imagesDir: images
:stylesDir: stylesheets

https://www.netlify.com/[Netlify] is an automated hosting platform for deploying static websites. With the aid of build tools such as Gradle, Netlify provides a smoother experience for previewing documentation. This can be done by using Netlify's https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/[Deploy Previews] feature, which shows a preview of the updated documentation whenever a pull request is made.

== Setting up Netlify
. Fork the repository to your own organization.
+
. Go to https://www.netlify.com/ and click `Sign Up`. Next, click `GITHUB SIGN IN`, enter your GitHub account details and authorize netlify.
+
. After logging in, click `New site from Git`.
+
. You will then be brought to the setup page. Click `GitHub` to link your repository to Netlify.
* Depending on whether you are the owner of the repository, you can either grant or request access to Netlify so that it can access your repository and build your documentation.
+
image:netlify/grant_or_request_access.png[Grant or request access, width = 630]
* After granting or requesting access to your repository, click `Authorize netlify`.
+
. Pick your repository from the list.
+
. Fill out the details as follows and then click `Deploy site`.
* Branch to deploy: select `master` branch
* Build command: `./gradlew asciidoctor`
+
[NOTE]
The build command is the command that builds the documentation into HTML format.
+
* Publish directory: `build/docs/html5`
[NOTE]
The publish directory is the directory in which the built HTML documentation resides.
+
. Once Netlify has completed building your project, you can now:
* View your main branch's deployed documentation on the site name given by Netlify (customizable as shown <<Changing the site name of your project, below>>).
+
image:netlify/temp_site_name.png[Temporary site name, width = 630]
+
* Preview the updated documentation whenever a pull request is made by clicking the `Details` hyperlink next to the Netlify test status.
+
image:netlify/netlify_details.png[Netlify details link, width = 630]

== Changing the site name of your project
If you don't like the site name given by Netlify, you can change it as follows:

. Click on `Settings`.
+
. Then click `Change site name` and fill in your desired site name.
+
image:netlify/change_site_name.png[Change site name, width = 630]
Loading

0 comments on commit b99339b

Please sign in to comment.