Readability improvements, and PR preview (#50)

* tweak readme, and website workflow to use different action

* add pr preview workflow

* fix readability in getting started, develop

* tweak nested lists

* fix nesting, workflow permissions

* try to fix format within list

* add workflow file

.github/workflows/deploy_website.yml

@@ -5,17 +5,30 @@ on:
       - main
 permissions:
   contents: write
+
 jobs:
   deploy:
+    concurrency: ci-${{ github.ref }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout sources
         uses: actions/checkout@v4
+
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
           python-version: 3.x
+
       - name: Install dependencies
         run: pip install mkdocs-material
+
+      - name: Build website
+        run: mkdocs build
+
       - name: Deploy website
-        run: mkdocs gh-deploy --force
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: site
+          branch: gh-pages
+          clean-exclude: pr-preview
+          force: false

.github/workflows/pr_preview.yml

@@ -0,0 +1,38 @@
+name: Deploy PR preview
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  deploy-preview:
+    concurrency: preview-${{ github.ref }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: pip install mkdocs-material
+
+      - name: Build website
+        if: github.event.action != 'closed'
+        run: mkdocs build
+
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: site
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview

README.md

@@ -1,5 +1,8 @@
 # Processing Library Template
-This is a template to help developers of Processing libraries to develop and release. 
+This is a template to help developers of Processing libraries to develop and release.
+
+Please read the [documentation website](https://mingness.github.io/processing-library-template/)
+for more information on how to use this template.
 
 Three important outputs are required to contribute a library to Processing, and this template provides 
 help and guidance on them. They are:
@@ -12,8 +15,6 @@ help and guidance on them. They are:
    release artifacts. If you host your code on Github, You can create a Github release that serves the 
    release artifacts.
 
-Please read the [documentation website](https://mingness.github.io/processing-library-template/)
-for more information on how to use this template.
 
 References for developing libraries for Processing can be found on the following Github wiki pages:
 - https://github.com/benfry/processing4/wiki/Library-Basics

docs/develop.md

@@ -15,9 +15,9 @@ in this template outputs the image shown on the home page.
 
 Also, existing references for developing libraries for Processing can be found on the following Github wiki pages:
 
-- [https://github.com/benfry/processing4/wiki/Library-Basics](https://github.com/benfry/processing4/wiki/Library-Basics)
-- [https://github.com/benfry/processing4/wiki/Library-Guidelines](https://github.com/benfry/processing4/wiki/Library-Guidelines)
-- [https://github.com/benfry/processing4/wiki/Library-Overview](https://github.com/benfry/processing4/wiki/Library-Overview)
+  - [https://github.com/benfry/processing4/wiki/Library-Basics](https://github.com/benfry/processing4/wiki/Library-Basics)
+  - [https://github.com/benfry/processing4/wiki/Library-Guidelines](https://github.com/benfry/processing4/wiki/Library-Guidelines)
+  - [https://github.com/benfry/processing4/wiki/Library-Overview](https://github.com/benfry/processing4/wiki/Library-Overview)
 
 Before following this guide, we recommend to follow the steps in the [getting started guide](getting-started.md)
 first.
@@ -38,21 +38,22 @@ be in the folder structure `src/main/java/com/myDomain/myLibrary/`.
 ## Resolving dependencies
 In the `build.gradle.kts` file, there are a few places you should edit, to input your own values.
 The part of the file that you are invited to edit is indicated by the comment 
-`USER BUILD CONFIGURATIONS`. We cover here how to add dependencies for your library. The 
+`USER BUILD CONFIGURATIONS`. We cover here how to add dependencies for your library. The relevant
 sections of the `build.gradle.kts` file are the `repositories` and `dependencies` sections.
 
 **The locations where dependencies will be resolved from are the `repositories`.** Most
 dependencies can be resolved from Maven. You can add additional repositories here if
 your dependencies are hosted elsewhere. 
 
-**Your dependencies should be listed within `dependencies`.** For example, the example
-library uses `org.apache.commons:commons-math3` as a dependency, which is resolved from
-your listed repositories. It is listed within `dependencies` with the following structure:
+**Your dependencies should be listed within `dependencies`.** For example, the example library
+uses the `commons-math3` package from `org.apache.commons` as a dependency, which is resolved
+from your listed repositories. It is listed within `dependencies` with the following structure:
+
 ```
-implementation("org.apache.commons:commons-math3:3.6.1")
+implementation(group = "org.apache.commons", name = "commons-math3", version = "3.6.1")
 ```
 
-This dependency, `org.apache.commons:commons-math3`, is only needed by the example library. 
+This dependency, `commons-math3`, is only needed by the example library. 
 You can delete this dependency for your own library. 
 Add your own dependencies using the same structure.
 
@@ -71,59 +72,63 @@ The section that you are invited to edit is indicated by the comment `USER BUILD
 We cover here how to configure the editable sections of the `build.gradle.kts` file, aside from
 those sections for [resolving dependencies](#resolving-dependencies).
 
-1. **Edit the variable `libName` to contain the name of your library**. The name can only contain
-   lower case alphanumeric characters, and "-". 
-   This value is used by Gradle to name the built jar file, and the zip file holding
-   your release artifacts. If this name does not match the name of the library in your code, 
-   as discussed in the section [Developing the library](#developing-the-library),
-   Processing will not find your library.
-2. **Edit the variable `group` with your own domain or organization name.** The group id 
-   of your library uniquely identifies your project. It's often written in reverse domain name 
-   notation. For example, if your website is "myDomain.com", your group ID would be "com.myDomain".
-3. **Define the `version` of your library in `build.gradle.kts`.** This value will also be
-   included in the release artifact `library.properties`. The version of your library usually 
-   follows semantic versioning (semver), which uses three numbers separated by dots: 
-   "MAJOR.MINOR.PATCH" (e.g., "1.0.0").
-   - MAJOR: Increases when you make incompatible changes.
-   - MINOR: Increases when you add new features that are backward-compatible.
-   - PATCH: Increases when you make backward-compatible bug fixes.
-
-   You will update these numbers as you release new versions of your library.
-4. The `sketchbookLocation` is determined programmatically by your operation system, and is
-   where your Processing `sketchbook` folder is. This folder contains your installed libraries.
-   It is needed if you:
-
-   1. wish to copy the library to the Processing sketchbook, which installs the library locally
-   2. have Processing library dependencies
+1.  **Edit the variable `libName` to contain the name of your library**. The name can only contain
+    lower case alphanumeric characters, and "-". 
+    This value is used by Gradle to name the built jar file, and the zip file holding
+    your release artifacts. If this name does not match the name of the library in your code, 
+    as discussed in the section [Developing the library](#developing-the-library),
+    Processing will not find your library.
+2.  **Edit the variable `group` with your own domain or organization name.** The group id 
+    of your library uniquely identifies your project. It's often written in reverse domain name 
+    notation. For example, if your website is "myDomain.com", your group ID would be 
+    "com.myDomain". This group id should match the group id discussed in 
+    section [Developing the library](#developing-the-library).
+3.  **Define the `version` of your library in `build.gradle.kts`.** This value will also be
+    included in the release artifact `library.properties`. The version of your library usually 
+    follows semantic versioning (semver), which uses three numbers separated by dots: 
+    "MAJOR.MINOR.PATCH" (e.g., "1.0.0"). 
+
+    - MAJOR: Increases when you make incompatible changes.
+    - MINOR: Increases when you add new features that are backward-compatible.
+    - PATCH: Increases when you make backward-compatible bug fixes.
+
+    You will update these numbers as you release new versions of your library.
+
+4.  The `sketchbookLocation` is determined programmatically by your operation system, and is
+    where your Processing `sketchbook` folder is. This folder contains your installed libraries.
+    It is needed if you:
+
+    1. wish to copy the library to the Processing sketchbook, which installs the library locally
+    2. have Processing library dependencies
 
-   This variable is in the editable section, in case the location determined is incorrect. A 
-   symptom of an incorrect `sketchbookLocation` is that your library does not show up in the
-   Contribution Manager in Processing, after being installed. Please look at our 
-   [troubleshooting guide](troubleshooting.md) if you suspect this is the case.
-
+    This variable is in the editable section, in case the location determined is incorrect. A 
+    symptom of an incorrect `sketchbookLocation` is that your library does not show up in the
+    Contribution Manager in Processing, after being installed. Please look at our 
+    [troubleshooting guide](troubleshooting.md) if you suspect this is the case.
+ 
 
 ## Creating the release artifacts
 If you've already gone through the [Getting started](getting-started.md#first-steps) guide, you will have
 already run Gradle tasks, and edited the `release.properties` file.
 
-1. Fill in the file `release.properties` with information for your library. This information will be
-   used by Gradle to create the `library.properties` file, which is one of the required release 
-   artifacts, used by the website and Contribution Manager to describe your library. In the file itself,
-   There are comments to guide you. To create just the `library.properties` file without building the
-   library, toggle `Tasks` > `processing` and double click `writeLibraryProperties`. This task will
-   copy all the values in `release.properties`, and also include the `version` in your `build.gradle.kts`
-   file as `prettyVersion`.
-2. **To build the library and create the release artifacts, run the Gradle task `releaseProcessingLib`.**
-   This task will create a `release` folder with needed artifacts. To do this, go to the Gradle menu 
-   (elephant), toggle `Tasks` > `processing` and double click `releaseProcessingLib`. This task 
-   has bundled the following required tasks:
-   1. `build` task: this bundles a number of build tasks, including the `jar` task which creates a
-      jar file. all build artifacts are in the folder `build`.
-   2. documentation build.
-   3. creation of the `library.properties` file: this file is built from the properties set in the
-      `release.properties` file, plus the version, in the task `writeLibraryProperties`.
-   4. within the `releaseProcessingLib` task, the `release` folder is created, jars of the library and
-      dependencies are copied, and the `library.properties` file is copied. Also, a zip file is made.
-3. When you would like to test your library in Processing, toggle `Tasks` > `processing` and double click
-   `deployToProcessingSketchbook`, which will create the release artifacts, and copy them into the 
-   sketchbook folder.
+1.  Fill in the file `release.properties` with information for your library. This information will be
+    used by Gradle to create the `library.properties` file, which is one of the required release 
+    artifacts, used by the website and Contribution Manager to describe your library. In the file itself,
+    There are comments to guide you. To create just the `library.properties` file without building the
+    library, toggle `Tasks` > `processing` and double click `writeLibraryProperties`. This task will
+    copy all the values in `release.properties`, and also include the `version` in your `build.gradle.kts`
+    file as `prettyVersion`.
+2.  **To build the library and create the release artifacts, run the Gradle task `releaseProcessingLib`.**
+    This task will create a `release` folder with needed artifacts. To do this, go to the Gradle menu 
+    (elephant), toggle `Tasks` > `processing` and double click `releaseProcessingLib`. This task 
+    has bundled the following required tasks:
+    1.  `build` task: this bundles a number of build tasks, including the `jar` task which creates a
+        jar file. all build artifacts are in the folder `build`.
+    2.  documentation build.
+    3.  creation of the `library.properties` file: this file is built from the properties set in the
+       `release.properties` file, plus the version, in the task `writeLibraryProperties`.
+    4.  within the `releaseProcessingLib` task, the `release` folder is created, jars of the library and
+        dependencies are copied, and the `library.properties` file is copied. Also, a zip file is made.
+3.  When you would like to test your library in Processing, toggle `Tasks` > `processing` and double click
+    `deployToProcessingSketchbook`, which will create the release artifacts, and copy them into the 
+    sketchbook folder.

docs/getting-started.md

@@ -29,18 +29,21 @@ You can use these interactions to test the library.
 1. **Open up your new repository in your chosen IDE.**
 2. **Run the Gradle task, deployToProcessingSketchbook**: The repository as is should build in Gradle. 
    In the Gradle menu (elephant) in your IDE, navigate to `Tasks` > `processing` > 
-   `deployToProcessingSketchbook`. This will run the Gradle task named `deployToProcessingSketchbook`.
+   `deployToProcessingSketchbook`, and double click on `deployToProcessingSketchbook`. 
+   This will run the Gradle task named `deployToProcessingSketchbook`.
    Running this task will build the library, create the release artifacts, and copy them into 
    where your installed libraries are stored.
 3. **The library can now be seen in the Contribution Manager.** Open Processing, and click on 
    `Sketch` > `Import Library ...` > `Manage Libraries ...`. This opens the Contribution Manager. 
    There should be an entry named "A Template Example Library" with a check mark next to it. 
-   That is the entry for the new library. If the library does not appear in the Contribution 
+   That is the entry for the example library that was installed in the previous step. 
+   If the library does not appear in the Contribution 
    Manager, please check the [troubleshooting guide](troubleshooting.md).
 4. **Customize what will be shown in the Contribution Manager for your library**:
    Open the file `release.properties` and change the value of the fields `name`, 
    `authors`, and `sentence`. Rerun the Gradle task, `deployToProcessingSketchbook`. This
-   will reinstall the library with the updated values.
+   will reinstall the library with the updated values, and these values should be visible
+   in the Contribution Manager.
 
 ## Next Steps
 Great, now you should be a little more familiar with the workings of the library template.

docs/release.md

@@ -26,8 +26,7 @@ The steps to deploying your MkDocs website with Github pages are below:
 
 1. You'll need to activate Github Pages and Github Actions for your project in the settings.
 2. In settings > Github Pages, set the Source to "Deploy from a branch."
-   Set the branch to `gh-pages` ; this branch is created by the
-   command `mkdocs gh-deploy`. Serve from the root folder.
+   Set the branch to `gh-pages`. Serve from the root folder.
 3. Edit the markdown files in the `docs`, and configure the navigation menu in `mkdocs.yml` file.
 4. Include the url of your website in the property named `url` in the `release.properties`. 
 
@@ -36,6 +35,6 @@ The steps to deploying your MkDocs website with Github pages are below:
 Releasing on Github provides an easy reference for stable versions.
 Github provides [documentation on releasing projects](https://docs.github.com/en/repositories/releasing-projects-on-github).
 When creating your release, use a tag that starts with "v". This triggers a Github
-workflow that will automatically upload the necessary release artifacts, such as the
-`*.txt`, `*.zip`, `*.pdex` files in your `release` folder. Github by default will
-include compressed versions of your source code only.
+workflow (`.github/workflows/release.yml`) that will automatically upload the necessary 
+release artifacts, such as the `*.txt`, `*.zip`, `*.pdex` files in your `release` folder. 
+Github by default will include compressed versions of your source code only.