diff --git a/.gitignore b/.gitignore index 9f11b755..bdca0b64 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ .idea/ +_site/ +_markbind/logs/ diff --git a/README.md b/README.md index a1f31aef..90b97e30 100644 --- a/README.md +++ b/README.md @@ -1,11 +1 @@ -# Guides and tutorials for SE student projects - -## Tutorials - -* [Gradle tutorial](tutorials/gradleTutorial.md) -* JavaFX tutorial: - * [Part 1: Introduction](tutorials/javaFxTutorialPart1.md) - * [Part 2: Creating a GUI for Duke](tutorials/javaFxTutorialPart2.md) - * [Part 3: Interacting with the user](tutorials/javaFxTutorialPart3.md) - * [Part 4: Using FXML](tutorials/javaFxTutorialPart4.md) - +Go to the main website [http://se-education.org/guides] diff --git a/_markbind/footers/footer.md b/_markbind/footers/footer.md new file mode 100644 index 00000000..e69de29b diff --git a/_markbind/headers/header.md b/_markbind/headers/header.md new file mode 100644 index 00000000..e69de29b diff --git a/_markbind/layouts/default/footer.md b/_markbind/layouts/default/footer.md new file mode 100644 index 00000000..e5f2864c --- /dev/null +++ b/_markbind/layouts/default/footer.md @@ -0,0 +1,6 @@ + diff --git a/_markbind/layouts/default/head.md b/_markbind/layouts/default/head.md new file mode 100644 index 00000000..e69de29b diff --git a/_markbind/layouts/default/header.md b/_markbind/layouts/default/header.md new file mode 100644 index 00000000..1b9b741d --- /dev/null +++ b/_markbind/layouts/default/header.md @@ -0,0 +1,17 @@ +
+ +SE-EDU +
  • AB-3
    • +
  • Book
    • + +
  • Home
    • +
  • About
    • +
  • {{ fab_github }} GitHub
    • +     +
  • +
    + +
    +
    • +     +
    diff --git a/_markbind/layouts/default/page.md b/_markbind/layouts/default/page.md new file mode 100644 index 00000000..166ad06d --- /dev/null +++ b/_markbind/layouts/default/page.md @@ -0,0 +1 @@ +{{ MAIN_CONTENT_BODY }} \ No newline at end of file diff --git a/_markbind/layouts/default/scripts.js b/_markbind/layouts/default/scripts.js new file mode 100644 index 00000000..eeeee412 --- /dev/null +++ b/_markbind/layouts/default/scripts.js @@ -0,0 +1,4 @@ +// eslint-disable-next-line no-undef +MarkBind.afterSetup(() => { + // Include code to be called after MarkBind setup here. +}); diff --git a/_markbind/layouts/default/styles.css b/_markbind/layouts/default/styles.css new file mode 100644 index 00000000..e69de29b diff --git a/_markbind/navigation/site-nav.md b/_markbind/navigation/site-nav.md new file mode 100644 index 00000000..85147b54 --- /dev/null +++ b/_markbind/navigation/site-nav.md @@ -0,0 +1,8 @@ + +* [Home :house:]({{ baseUrl }}/index.html) +* [Topic 1]({{baseUrl}}/contents/topic1.html) +* [Topic 2]({{baseUrl}}/contents/topic2.html) +* Topic 3 :expanded: + * [Topic 3a]({{baseUrl}}/contents/topic3a.html) + * [Topic 3b]({{baseUrl}}/contents/topic3b.html) + \ No newline at end of file diff --git a/_markbind/variables.json b/_markbind/variables.json new file mode 100644 index 00000000..04d0b977 --- /dev/null +++ b/_markbind/variables.json @@ -0,0 +1,3 @@ +{ + "jsonVariableExample": "Your variables can be defined here as well" +} \ No newline at end of file diff --git a/_markbind/variables.md b/_markbind/variables.md new file mode 100644 index 00000000..24522dbe --- /dev/null +++ b/_markbind/variables.md @@ -0,0 +1,39 @@ +:fas-bell: +:fas-book: +:fas-calendar-alt: +:fas-thumbs-down: +:fas-cube: +:glyphicon-log-in: +:fas-dumbbell: +:fas-plus: extra +:fas-info-circle: +:fas-thumbs-up: +:fab-linux: +:glyphicon-exclamation-sign: +:glyphicon-exclamation-sign: +:glyphicon-new-window: +:fas-trophy: +:fas-arrow-down: +:fas-arrow-right: +:glyphicon-print: +:glyphicon-education: +:glyphicon-eye-open: +:fas-lightbulb: PRO TIP +:glyphicon-question-sign: +{{ icon_Q | safe }}:glyphicon-ok-sign: +:fas-paperclip: +>_ +:far-file-alt: +:fas-check: +:fas-lightbulb: +{{ icon_tick | safe }} +:glyphicon-check: +:far-images: +:glyphicon-facetime-video: +:fab-windows: +:fas-times: +{{ icon_x | safe }} +**{{ icon_dislike | safe }} Bad** +**{{ icon_like | safe }} Good** + + \ No newline at end of file diff --git a/about.md b/about.md new file mode 100644 index 00000000..e436f377 --- /dev/null +++ b/about.md @@ -0,0 +1,29 @@ + + title: "About Us" + + +
    + +{{ booktitle | safe }} + +# About Us + +This is a sub-project of the [SE-EDU Project](https://se-edu.github.io). + + +## Contact + +Suggestions, questions, and bug reports can be posted in [our issue tracker](https://github.com/nus-oss/learningresources/issues). + + +Alternatively, contact project mentor [Damith C. Rajapakse](https://www.comp.nus.edu.sg/~damithch). + + +## License + +MIT + +## Acknowledgements + +* The `favicon.ico` is based on an icon made by [Dave Gandy](https://www.flaticon.com/authors/dave-gandy) from www.flaticon.com +
    diff --git a/favicon.ico b/favicon.ico new file mode 100644 index 00000000..96613534 Binary files /dev/null and b/favicon.ico differ diff --git a/index.md b/index.md new file mode 100644 index 00000000..66b821cd --- /dev/null +++ b/index.md @@ -0,0 +1,16 @@ + + title: "Guides for Software Engineering Students" + pageNav: 2 + + +# Guides and tutorials for SE student projects + +## Tutorials + +* [Gradle](tutorials/gradleTutorial.html) +* JavaFX: + * [Part 1: Introduction](tutorials/javaFxTutorialPart1.html) + * [Part 2: Creating a GUI for Duke](tutorials/javaFxTutorialPart2.html) + * [Part 3: Interacting with the user](tutorials/javaFxTutorialPart3.html) + * [Part 4: Using FXML](tutorials/javaFxTutorialPart4.html) +* [Automated testing of text UIs](tutorials/textUiTestingTutorial.html) diff --git a/site.json b/site.json new file mode 100644 index 00000000..0a27061c --- /dev/null +++ b/site.json @@ -0,0 +1,24 @@ +{ + "baseUrl": "/guides", + "titlePrefix": "", + "timeZone": "Asia/Singapore", + "ignore": [ + "_markbind/layouts/*", + "_markbind/logs/*", + "_site/*", + "site.json", + "*.md", + "*.mbd", + "*.mbdf", + "*.njk", + ".git/*" + ], + "pages": [ + { + "glob": ["**/*.+(md|mbd)"] + } + ], + "deploy": { + "message": "Site Update." + } +} diff --git a/tutorials/checkstyleTutorial.md b/tutorials/checkstyleTutorial.md index 2fd9f957..1ec6bb2c 100644 --- a/tutorials/checkstyleTutorial.md +++ b/tutorials/checkstyleTutorial.md @@ -1 +1,6 @@ -TBD \ No newline at end of file + + title: "CheckStyle Tutorial" + pageNav: 2 + + +TBD diff --git a/tutorials/gradleTutorial.md b/tutorials/gradleTutorial.md index 26c67dd1..d75a0dc3 100644 --- a/tutorials/gradleTutorial.md +++ b/tutorials/gradleTutorial.md @@ -1,3 +1,8 @@ + + title: "Gradle Tutorial" + pageNav: 2 + + # Gradle Tutorial Gradle is a _build automation tool_ used to automate build processes. There are many ways of integrating Gradle into a project. This tutorial uses the _Gradle wrapper_ approach. @@ -27,13 +32,33 @@ Tasks can be composed of, or dependent on, other tasks. ## Adding Gradle to the project -For simplicity, let us assume that Gradle Wrapper has been added to the project already (if it has been added to the project, you will see a `gradle\wrapper\gradle-wrapper.jar` in your project). If you need to add it yourself, you can learn how to do that from [here](https://docs.gradle.org/current/userguide/gradle_wrapper.html). +****Scenario 1:**** You are setting up a project in Intellij IDEA. The project already has Gradle support. + +
    + +{{ icon_tip }} If the project comes with Gradle support, you will see a `build.gradle` file in your project root. +
    + +1. When you _import_ the project into IDEA, at the step where you normally select the project root folder, choose the `build.gradle` file inside the root folder instead. +1. If asked, choose `Open as Project` (not `Open as File`). +1. After importing is complete, you will see the `Gradle Toolbar` in the IDEA interface.
    + ![Gradle icon](assets/GradleIcon.png) + +****Scenario 2:**** You are adding Gradle support to an ongoing project that is already set up in Intellij IDEA. Gradle wrapper files have been provided. + +1. Add the Gradle wrapper files to the project. e.g., if they are in a separate branch, merge that branch. +1. Close the IDEA project if it is open. +1. Delete the `.idea` folder. +1. Import the project again (similar to scenario 1 above) + +****Scenario 3:**** You are adding Gradle support to an ongoing project from scratch. + +* You are on you own but [this](https://docs.gradle.org/current/userguide/gradle_wrapper.html) is a good place to start. ## Using Gradle in Intellij IDEA -When you import a Gradle project into IntelliJ IDEA, you should select the `build.gradle` instead of the project root directory. After importing a Gradle project into Intellij IDEA, you will see the `Gradle Toolbar` in the IDEA interface.
    -![Gradle icon](assets/GradleIcon.png) + If the Gradle tasks don't appear in the Gradle window, click the 'refresh' button in the tooolbar to reimport the Gradle project. diff --git a/tutorials/javaFxTutorialPart1.md b/tutorials/javaFxTutorialPart1.md index b18ac93d..7b307cc4 100644 --- a/tutorials/javaFxTutorialPart1.md +++ b/tutorials/javaFxTutorialPart1.md @@ -1,3 +1,8 @@ + + title: "JavaFX Tutorial Part 1 – Introduction" + pageNav: 2 + + # JavaFX Tutorial Part 1 – Introduction ## Lifecycle of a JavaFX application diff --git a/tutorials/javaFxTutorialPart2.md b/tutorials/javaFxTutorialPart2.md index f24a0cd6..ac1d532f 100644 --- a/tutorials/javaFxTutorialPart2.md +++ b/tutorials/javaFxTutorialPart2.md @@ -1,3 +1,8 @@ + + title: "JavaFX Tutorial Part 2 - Creating a GUI for Duke" + pageNav: 2 + + # JavaFX Tutorial Part 2 - Creating a GUI for Duke In this tutorial, we will be creating a GUI for Duke from scratch based on the following mockup. diff --git a/tutorials/javaFxTutorialPart3.md b/tutorials/javaFxTutorialPart3.md index 54bc7e3d..0b4bd909 100644 --- a/tutorials/javaFxTutorialPart3.md +++ b/tutorials/javaFxTutorialPart3.md @@ -1,3 +1,8 @@ + + title: "JavaFX Tutorial 3 – Interacting with the user" + pageNav: 2 + + # JavaFX Tutorial 3 – Interacting with the user Picking up from where we left off last tutorial, we have successfully achieved the desired layout. Now let’s make the application respond to user input. diff --git a/tutorials/javaFxTutorialPart4.md b/tutorials/javaFxTutorialPart4.md index 188c4ef2..490b4280 100644 --- a/tutorials/javaFxTutorialPart4.md +++ b/tutorials/javaFxTutorialPart4.md @@ -1,3 +1,8 @@ + + title: "JavaFX Tutorial Part 4 – Using FXML" + pageNav: 2 + + # JavaFX Tutorial Part 4 – Using FXML While we have produced a fully functional prototype, there are a few major problems with our application. diff --git a/tutorials/junitTutorial.md b/tutorials/junitTutorial.md index fce79db2..8fbaef07 100644 --- a/tutorials/junitTutorial.md +++ b/tutorials/junitTutorial.md @@ -1,3 +1,8 @@ + + title: "JUnit Tutorial" + pageNav: 2 + + JUnit is a testing framework for Java. By convention, java tests belong in `src/test/java` folder. A sample test file is included in this project. * To run a specific JUnit test class (e.g., `src/test/java/DukeTest.java`), right-click on the test class, and choose `Run {classname}`. diff --git a/tutorials/textUiTestingTutorial.md b/tutorials/textUiTestingTutorial.md index f397d76a..df238174 100644 --- a/tutorials/textUiTestingTutorial.md +++ b/tutorials/textUiTestingTutorial.md @@ -1,9 +1,23 @@ -# Text UI Testing Tutorial + + title: "Tutorial: Automated testing of text UIs" + pageNav: 2 + -1. Create a folder `[project root]\text-ui-test` +# Tutorial: Automated testing of text UIs + +_I/O redirection_ technique can be used to semi-automate the testing of text UIs. For an explantion of how that technique works, see [the _Automated Testing of CLI Apps_ section of se-edu/se-book](https://se-education.org/se-book/testing/#automated-testing-of-cli-apps). + +## Setting up + +Given below re steps to set it up for a project. + +1. Create a folder to hold the relevant files e.g., `[project root]\text-ui-test` 1. Add a `runtest.bat` (if you are on Windows) or `runtest.sh` (if you are on a *nix OS) into the folder, containing the script below.
    - `runtest.bat`: - ``` + + + + + ```bat @ECHO OFF REM create bin directory if it doesn't exist @@ -26,9 +40,10 @@ REM compare the output to the expected output FC ACTUAL.TXT EXPECTED.TXT ``` + + - `runtest.sh`: - ```shell + ```sh #!/usr/bin/env bash # create bin directory if it doesn't exist @@ -64,10 +79,40 @@ exit 1 fi ``` -1. Update the `javac` and `java` commands in the script to match the name/location of your main class. + + +
    + +1. Update the `javac` and `java` commands in the script to match the name/location of your main class.
    + If you are using packages, the two commands need to take the packages into account too. 1. Add an `EXPECTED.txt` to the same folder, containing the expected output. 1. Add an `input.txt` containing the input commands. 1. Run the `.bat`/`.sh` file to execute the test. + * If the actual output matches the EXPECTED.TXT, the test passes. + * If the actual output differs from the EXPECTED.TXT, the script will report a failure. + + +## Updating tests as the program evolves + +The purpose of testing as explained in the previous section is to confirm there are no _regressions_. However, we often update the behavior of the program intentionally e.g., enhance an existing feature. Let's look at how to update our test set up in those cases. + +**Option 1:** This is the ideal but more tedious approach. +1. Determine how the expected behavior _should_ change due to your update to the code. +1. Update the `EXPECTED.TXT` file accordingly. +1. Run the test to confirm the actual behavior is same as the _updated_ expected behavior. + +**Option 2:** This is a more practical shortcut. +1. Run the test as per normal after updating the code. The test will fail because the new program behavior is different from the one given in the `EXPECTED.TXT`. +1. Use a diff tool to compare the `ACTUAL.TXT` against the `EXPECTED.TXT`.
    + {{ icon_tip }} [Intellij IDEA can compare two files](https://www.jetbrains.com/help/idea/comparing-files-and-folders.html). +1. Confirm the differences indicate the behavior has changed as you intended. If the differences are not as intended, your code is buggy; fix the code and repeat from step 1. +1. Copy over the content of the `ACTUAL.TXT` to `EXPECTED.TXT` i.e., we accept that the actual behavior should be the new _expected_ behavior. Rerun the test to confirm that it passes this time. + +## Troubleshooting + +* **Problem**: The `ACTUAL.TXT` and `EXPECTED.TXT` looks exactly the same but the test fails.
    +**Explanation**: The likely cause that the line endings are different (not visible to the naked eye) because the two files were created in two different operating systems.
    +**Solution**: You can use the `dos2unix` utility (available in git-bash and *nix operating systems) to convert a file to Unix format. -------------------------------------------------------------------------------- **Authors:**