Merge pull request #735 from soot-oss/doc_keep_install_up2date

update version in doc:installation automatically

.github/workflows/gh-pages.yml

@@ -1,26 +1,97 @@
-name: Documentation 
+# see https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/
+# execute once, after the first deployment has 'latest' as alias:
+# mike set-default latest --push
+
+name: Documentation
+
 on:
   push:
-    branches: 
+    branches:
       - develop
-    # only trigger workflow if one of these paths are affected as well
     paths:
       - 'mkdocs.yml'
       - 'sootup.examples/**'
       - 'docs/**'
 
+  release:
+    types: [ created, published ]
+
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+    paths:
+      - 'mkdocs.yml'
+      - 'sootup.examples/**'
+      - 'docs/**'
+
+concurrency: pages
+
+permissions:
+  contents: write
+  pull-requests: write
+
 jobs:
-  deploy:
+  manage:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
+      # to get tag information
+      - run: git fetch --prune --unshallow
+
       - uses: actions/setup-python@v2
         with:
           python-version: 3.x
+
+      # install dependencies
+      - run: pip install mike
       - run: pip install mkdocs-material
       - run: pip install mkdocs-tooltips
       - run: pip install git+https://github.com/RedisLabs/mkdocs-include.git
       - run: pip install git+https://github.com/swissiety/LspLexer4Pygments.git
       # grab latest release url of the JimpleLSP jar and download it
       - run: curl -s -L -o ./jimplelsp.jar $(curl -s https://api.github.com/repos/swissiety/jimpleLsp/releases/latest | grep 'browser_download_url".*jar"' | cut -d ':' -f 2,3 | tr -d \")
-      - run: mkdocs gh-deploy --force
+
+      - name: replace "{{ git_latest_release }}" with latest release tag version in .md files
+        run: sed -i 's\{{ git_latest_release }}\'$(git tag --sort=committerdate | grep -E '[0-9]' | tail -1 | cut -b 2-7)'\g' docs/**.md
+
+      - run: git fetch origin gh-pages --depth=1
+      - name: Configure git user
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+
+      # on push to develop branch - keep a doc around for develop to show the current state
+      - name: deploy doc in subdirectory
+        if: github.event_name == 'push'
+        run: mike deploy develop
+
+      # on PR events..
+      - name: deploy doc in subdirectory
+        if: github.event_name == 'pull_request'
+        run: mike deploy ${{ github.head_ref }}_preview --push
+        # TODO: set to true when the release is capable of the documentation ;)  && mike props ${{ github.head_ref }}_preview --set-string hidden=true --push
+
+      - name: comment link to preview
+        if: github.event_name == 'pull_request' && github.event.action != 'closed'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          message: |
+            You updated the documentation - [Doc Preview](https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}_preview/${{ github.head_ref }}/).
+
+      # on PR close - delete preview
+      - name: delete the deployed preview
+        if: github.event_name == 'pull_request' && github.event.action == 'closed'
+        run: mike delete ${{ github.head_ref }}_preview --push
+
+
+      # on release events..
+      - name: deploy doc in subdirectory
+        if: github.event_name == 'release'
+        run: mike deploy ${{ github.ref_name }} --push
+
+      - name: set the new release doc as default (release published)
+        if: github.event_name == 'release' && github.event.action == 'published'
+        run: mike deploy --push --update-aliases ${{ github.ref_name }} latest

.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Create Release Draft
+
+on:
+  push:
+    tags:
+      # Push events to matching
+      - ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$
+
+jobs:
+  build:
+    name: Create Release Draft
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@master
+      - name: Create Release
+        id: create_release
+        uses: actions/create-release@latest
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: ${{ github.ref }}
+          body: |
+            **TODO:** update changes in this Release
+            - First Change
+            - Second Change
+            - ...
+            [Documentation](https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ github.ref }}/
+          draft: true
+          prerelease: false

docs/index.md

@@ -27,7 +27,7 @@ So we introduced [Design changes in SootUp](whatsnew.md), which aim to address S
 The goal is a lighter library that can easily be understood and maintained to be included in other projects.
 
 ### Is this a drop-in replacement for Soot?
-Not really. SootUp has a completely new architecture and API, so it is not trivial to update existing projects that build on soot. We recommend using it for greenfield projects.
+Not really. SootUp has a completely new architecture and API, so it is not trivial to update existing projects that build on soot. We recommend using SootUp for greenfield projects.
 
 
 ## Supporters

docs/installation.md

@@ -15,37 +15,37 @@ Take a look at the [Modules](whatsnew.md#modular-architecture) to learn more abo
  <dependency>
    <groupId>org.soot-oss</groupId>
    <artifactId>sootup.core</artifactId>
-   <version>1.0.0</version>
+   <version>{{ git_latest_release }}</version>
  </dependency>
  <dependency>
   <groupId>org.soot-oss</groupId>
   <artifactId>sootup.java.core</artifactId>
-  <version>1.0.0</version>
+  <version>{{ git_latest_release }}</version>
  </dependency>
  <dependency>
   <groupId>org.soot-oss</groupId>
   <artifactId>sootup.java.sourcecode</artifactId>
-  <version>1.0.0</version>
+  <version>{{ git_latest_release }}</version>
  </dependency>
  <dependency>
   <groupId>org.soot-oss</groupId>
   <artifactId>sootup.java.bytecode</artifactId>
-  <version>1.0.0</version>
+  <version>{{ git_latest_release }}</version>
  </dependency>
  <dependency>
   <groupId>org.soot-oss</groupId>
   <artifactId>sootup.jimple.parser</artifactId>
-  <version>1.0.0</version>
+  <version>{{ git_latest_release }}</version>
  </dependency>
  <dependency>
   <groupId>org.soot-oss</groupId>
   <artifactId>sootup.callgraph</artifactId>
-  <version>1.0.0</version>
+  <version>{{ git_latest_release }}</version>
  </dependency>
  <dependency>
   <groupId>org.soot-oss</groupId>
   <artifactId>sootup.analysis</artifactId>
-  <version>1.0.0</version>
+  <version>{{ git_latest_release }}</version>
  </dependency>
 </dependencies>
 ```
@@ -54,13 +54,13 @@ Take a look at the [Modules](whatsnew.md#modular-architecture) to learn more abo
 Add the following dependency in the ```build.gradle``` file of your project to include all SootUp modules into your project.
 
 ```
-compile "org.soot-oss:sootup.core:1.0.0"
-compile "org.soot-oss:sootup.java.core:1.0.0"
-compile "org.soot-oss:sootup.java.sourcecode:1.0.0"
-compile "org.soot-oss:sootup.java.bytecode:1.0.0"
-compile "org.soot-oss:sootup.jimple.parser:1.0.0"
-compile "org.soot-oss:sootup.callgraph:1.0.0"
-compile "org.soot-oss:sootup.analysis:1.0.0"
+compile "org.soot-oss:sootup.core:{{ git_latest_release }}"
+compile "org.soot-oss:sootup.java.core{{ git_latest_release }}"
+compile "org.soot-oss:sootup.java.sourcecode{{ git_latest_release }}"
+compile "org.soot-oss:sootup.java.bytecode{{ git_latest_release }}"
+compile "org.soot-oss:sootup.jimple.parser{{ git_latest_release }}"
+compile "org.soot-oss:sootup.callgraph{{ git_latest_release }}"
+compile "org.soot-oss:sootup.analysis{{ git_latest_release }}"
 ```
 
 ## Building from Source
@@ -79,7 +79,7 @@ Alternatively, you can execute the following command in the project directory:
 mvn install
 ```
 
-Or if you want to skip unit tests while building:
+Or if you want to skip tests while building:
 
 ```
 mvn -Dskiptests install

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: SootUp
-#site_url: https://example.com/
+site_url: https://soot-oss.github.io/SootUp/
 repo_url: https://github.com/soot-oss/SootUp/
 edit_uri: edit/develop/docs/
 
@@ -57,3 +57,6 @@ markdown_extensions:
   - pymdownx.tabbed:
       alternate_style: true
 
+extra:
+  version:
+    provider: mike