From cd351ad9e879bc11e303a459206aa4717552a66c Mon Sep 17 00:00:00 2001 From: damithc Date: Mon, 25 May 2020 16:47:25 +0800 Subject: [PATCH] Convert to MarkBind format --- .gitignore | 2 + README.md | 12 +----- _markbind/footers/footer.md | 0 _markbind/headers/header.md | 0 _markbind/layouts/default/footer.md | 6 +++ _markbind/layouts/default/head.md | 0 _markbind/layouts/default/header.md | 17 ++++++++ _markbind/layouts/default/page.md | 1 + _markbind/layouts/default/scripts.js | 4 ++ _markbind/layouts/default/styles.css | 0 _markbind/navigation/site-nav.md | 8 ++++ _markbind/variables.json | 3 ++ _markbind/variables.md | 39 ++++++++++++++++++ about.md | 29 +++++++++++++ favicon.ico | Bin 0 -> 2901 bytes index.md | 16 ++++++++ site.json | 24 +++++++++++ tutorials/checkstyleTutorial.md | 7 +++- tutorials/gradleTutorial.md | 31 ++++++++++++-- tutorials/javaFxTutorialPart1.md | 5 +++ tutorials/javaFxTutorialPart2.md | 5 +++ tutorials/javaFxTutorialPart3.md | 5 +++ tutorials/javaFxTutorialPart4.md | 5 +++ tutorials/junitTutorial.md | 5 +++ tutorials/textUiTestingTutorial.md | 59 +++++++++++++++++++++++---- 25 files changed, 261 insertions(+), 22 deletions(-) create mode 100644 _markbind/footers/footer.md create mode 100644 _markbind/headers/header.md create mode 100644 _markbind/layouts/default/footer.md create mode 100644 _markbind/layouts/default/head.md create mode 100644 _markbind/layouts/default/header.md create mode 100644 _markbind/layouts/default/page.md create mode 100644 _markbind/layouts/default/scripts.js create mode 100644 _markbind/layouts/default/styles.css create mode 100644 _markbind/navigation/site-nav.md create mode 100644 _markbind/variables.json create mode 100644 _markbind/variables.md create mode 100644 about.md create mode 100644 favicon.ico create mode 100644 index.md create mode 100644 site.json 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 0000000000000000000000000000000000000000..96613534a2a43b5d37ec473ae63fca8d0ee1b5d3 GIT binary patch literal 2901 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 literal 0 HcmV?d00001 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:**