From 99c783db9089d3aa8eaacffd4d3e13eb30df0382 Mon Sep 17 00:00:00 2001 From: mingness Date: Sun, 15 Sep 2024 16:40:04 +0200 Subject: [PATCH] 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 | 15 +++- .github/workflows/pr_preview.yml | 38 +++++++++ README.md | 7 +- docs/develop.md | 123 ++++++++++++++------------- docs/getting-started.md | 9 +- docs/release.md | 9 +- 6 files changed, 130 insertions(+), 71 deletions(-) create mode 100644 .github/workflows/pr_preview.yml diff --git a/.github/workflows/deploy_website.yml b/.github/workflows/deploy_website.yml index 9e7a76a..c4cd385 100644 --- a/.github/workflows/deploy_website.yml +++ b/.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 diff --git a/.github/workflows/pr_preview.yml b/.github/workflows/pr_preview.yml new file mode 100644 index 0000000..f0beecd --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index ae074c9..8daa7ca 100644 --- a/README.md +++ b/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 diff --git a/docs/develop.md b/docs/develop.md index d619113..02d71e8 100644 --- a/docs/develop.md +++ b/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. diff --git a/docs/getting-started.md b/docs/getting-started.md index 6507aad..7513904 100644 --- a/docs/getting-started.md +++ b/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. diff --git a/docs/release.md b/docs/release.md index 1410cc0..27f4aa3 100644 --- a/docs/release.md +++ b/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.