contrib: add community contrib feature

.github/ci/build_contrib.sh

@@ -0,0 +1,16 @@
+# !/bin/bash
+
+mapfile themes <contrib.txt
+# All contrib template should only have one entry point.
+for theme in ${themes[@]};
+do
+    theme=${theme:1:${#theme}-2}    # remove the /
+    echo Compiling $theme documentation...
+    cp contrib/$theme/$theme.tex ./$theme.tex
+    latexmk $@ -outdir=build $theme.tex
+    echo Compiling $theme preview ...
+    sed -e "s|<theme>|$theme|g" src/doc/contrib.template.tex > build/contrib.$theme.tex
+    latexmk $@ -outdir=build build/contrib.$theme.tex
+    echo Converting $theme to png...
+    convert -verbose -density 500 -resize '1280' build/contrib.$theme.pdf build/contrib.$theme.png
+done

.github/workflows/build.yml

@@ -3,10 +3,16 @@ on:
     branches:
       - main
       - develop
+    paths:
+      - '**'
+      - '!contrib/**'
   pull_request:
     branches:
       - main
       - develop
+    paths:
+      - '**'
+      - '!contrib/**'
 
 name: Build
 

.github/workflows/contrib.yml

@@ -0,0 +1,91 @@
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'contrib/**'
+  pull_request:
+    branches:
+      - main
+      - develop
+    types:
+      - 'review_requested'
+    paths:
+      - 'contrib/**'
+
+name: Contrib
+
+jobs:
+  build-contrib:
+    runs-on: ubuntu-latest
+    # permission to the environment will 
+    # need to be approved by one of the collaborators
+    environment: IMGUR
+    steps: 
+      - uses: actions/checkout@v2
+        name: checkout code
+        with:
+          fetch-depth: 0
+      - name: get newly contributed package
+        run: |
+          git diff origin/main --name-only | grep -e 'contrib\/[^/]*\/sjtubeamertheme[^/]*\.ltx' | grep -o -e '\/[^/]*\/' > contrib.txt
+      - uses: xu-cheng/texlive-action/full@v1
+        with:
+          run: |
+            apk add ghostscript imagemagick gnupg
+            sed -i "s|<policy domain=\"coder\" rights=\"none\" pattern=\"PDF\" />|<policy domain=\"coder\" rights=\"read\|write\" pattern=\"PDF\" />|g" /etc/ImageMagick-*/policy.xml
+            .github/ci/build_contrib.sh -halt-on-error -time -quiet -xelatex
+        name: build contrib doc with XeLaTeX
+      - uses: actions/upload-artifact@v2
+        with:
+          path: |
+            build/contrib.*.pdf
+        name: upload contrib artifacts
+      - uses: devicons/public-upload-to-imgur@v2.2.2
+        id: contrib_png
+        with:
+          path: ./build/contrib.*.png
+          client_id: ${{secrets.IMGUR_CLIENT_ID}}
+        name: upload contrib img to imgur
+      - uses: jungwinter/comment@v1
+        if: github.event_name == 'pull_request'
+        env:
+          MESSAGE: |
+            Thank you for contributing to SJTUBeamer! 
+
+            Here is the preview of your contribution documentation.
+
+            {0}
+        with:
+          type: create
+          issue_number: ${{ github.event.number }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          body: >
+            ${{ 
+              format(
+                env.MESSAGE,
+                join(fromJSON(steps.contrib_png.outputs.markdown_urls), '  ')
+              )
+            }}
+      - uses: jungwinter/comment@v1
+        if: github.event_name == 'push'
+        env:
+          MESSAGE: |
+            ###{0}
+
+            @{1}
+
+            {2}
+        with:
+          type: create
+          issue_number: '77' # to be replaced by the good first issue number, open issues only.
+          token: ${{ secrets.GITHUB_TOKEN }}
+          body: >
+            ${{
+              format(
+                env.MESSAGE,
+                github.event.push.commits[0].message,
+                github.event.push.commits[0].author.name,
+                join(fromJSON(steps.contrib_png.outputs.markdown_urls), '  ')
+              )
+            }}

.gitignore

@@ -266,4 +266,5 @@ cover.pdf
 sjtubeamer*.pdf
 cover-*.pdf
 basis-*.tex
-step*.pdf
+step*.pdf
+contrib/*/*.pdf

.vscode/settings.json

@@ -0,0 +1 @@
+{}

CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# 向 SJTUBeamer 贡献插件
+
+SJTUBeamer 现在已经开放插件接口，存放于根目录的 `contrib/` 文件夹中。如果您实现了自己的主题模板，或者是基于 SJTUBeamer API 的宏包，可以考虑通过下面的步骤向本存储库发 PR：
+1. fork 仓库，克隆自己的仓库到本地。
+2. 向你的电脑安装当前版本的 SJTUBeamer，`cd src && l3build install`，便于插件文档的编写。
+3. 在 `contrib` 文件夹中新建一个插件文件夹 `<theme>`
+4. 在文件夹中至少应该有下面两个文件：
+    - 插件入口 `contrib/<theme>/sjtubeamertheme<theme>.ltx`
+    - 插件文档 `contrib/<theme>/<theme>.tex`
+5. 如果在插件中需要使用相对于该插件目录的文件，请使用下面的 API：
+    - `\getcontribdir{<theme>}` 返回插件目录 `contrib/<theme>`
+    - `\getcontribpath{<theme>}{<filepath>}` 返回插件文件 `contrib/<theme>/<filepath>`
+6. 发 PR 时，使用 `contrib: <theme>` 作为标题，并向维护者发出代码审查请求。
+7. 之后在根目录的主文件中就可以在 `\usetheme{sjtubeamer}` 后使用 `\usemytheme{<theme>}` 调用你的插件。
+
+更多信息，请参阅开发文档。
+
+-----
+
+# Contribute to SJTUBeamer
+
+SJTUBeamer is available for receiving plugins, which are stored in `contrib/` folder. If you want to contribute your own theme template or package based on SJTUBeamer API, you could make a pull request to this repo by the following steps:
+1. Fork this repository and clone your own version to the machine.
+2. Install the current version of `SJTUBeamer` to your computer for the convenience of writing documentation.
+`cd src && l3build install`.
+3. Create a new plugin folder `<theme>` in `contrib`.
+4. At least two files should be implemented in the folder:
+    - Plugin entry point. `contrib/<theme>/sjtubeamertheme<theme>.ltx`
+    - Plugin documentation. `contrib/<theme>/<theme>.tex`
+5. If you want to use the file in your plugin directory, use the following API:
+    - `\getcontribdir{<theme>}` returns the plugin directory `contrib/<theme>`
+    - `\getcontribpath{<theme>}{<filepath>}` returns plugin file path `contrib/<theme>/<filepath>`
+6. Pull request to this repo naming `contrib: <theme>`, request a review from one of the collaborators.
+7. Now, you could call your plugin by using `\usemytheme{<theme>}` after `\usetheme{sjtubeamer}`.
+
+For more information, please refer to the development guide.