chore(documentation): #1311 add documentation for black border #321
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # Copyright (c) 2023 Contributors to the Eclipse Foundation | |
| # | |
| # See the NOTICE file(s) distributed with this work for additional | |
| # information regarding copyright ownership. | |
| # | |
| # This program and the accompanying materials are made available under the | |
| # terms of the Apache License, Version 2.0 which is available at | |
| # https://www.apache.org/licenses/LICENSE-2.0. | |
| # | |
| # Unless required by applicable law or agreed to in writing, software | |
| # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT | |
| # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the | |
| # License for the specific language governing permissions and limitations | |
| # under the License. | |
| # | |
| # SPDX-License-Identifier: Apache-2.0 | |
| name: "[BE][FE][DOCUMENTATION] Publish documentation" | |
| on: | |
| workflow_dispatch: # Trigger manually | |
| pull_request: | |
| paths: | |
| - 'docs/**' | |
| push: | |
| branches: | |
| - main | |
| paths: | |
| - 'docs/**' | |
| jobs: | |
| publish: | |
| # depending on default permission settings for your org (contents being read-only or read-write for workloads), you will have to add permissions | |
| # see: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token | |
| permissions: | |
| contents: write | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - name: Setup Graphviz | |
| uses: ts-graphviz/setup-graphviz@v2 | |
| - name: Set up JDK 17 | |
| uses: actions/setup-java@v4 | |
| with: | |
| java-version: '17' | |
| distribution: 'temurin' | |
| - name: Setup Node | |
| uses: actions/setup-node@v4 | |
| with: | |
| node-version: 20 | |
| - name: Cache maven packages | |
| uses: actions/cache@v4 | |
| with: | |
| path: ~/.m2 | |
| key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }} | |
| restore-keys: ${{ runner.os }}-m2 | |
| - name: Build with Maven | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Needed to get PR information, if any | |
| run: | | |
| mvn -f docs/pom.xml --batch-mode generate-resources | |
| - name: Install Asciidoctor Reducer | |
| run: | | |
| sudo gem install asciidoctor-reducer | |
| - name: Reduce docs | |
| run: | | |
| echo $LANG | |
| locale | |
| asciidoctor-reducer -o docs/target/adminguide.adoc docs/src/docs/administration/administration-guide.adoc | |
| asciidoctor-reducer -o docs/target/arc42.adoc docs/src/docs/arc42/full.adoc | |
| asciidoctor-reducer -o docs/target/user-manual.adoc docs/src/docs/user/user-manual.adoc | |
| - name: Cache plantuml jar | |
| uses: actions/cache@v3 | |
| with: | |
| path: plantuml.jar | |
| key: ${{ runner.os }}-file-${{ hashFiles('plantuml.jar') }} | |
| - name: Download PlantUML jar | |
| run: | | |
| wget -O plantuml.jar https://sourceforge.net/projects/plantuml/files/plantuml.jar/download | |
| - name: Place PlantUML jar in specific path | |
| run: | | |
| mv plantuml.jar docs/src/diagram-replacer/ | |
| - name: Extract PNG-Images with PlantUML and replace PlantUML Code inside docs with PNG-Images | |
| working-directory: docs/src/diagram-replacer/ | |
| run: | | |
| node extract.js | |
| node replace.js | |
| - name: Convert to Markdown | |
| run: | | |
| npx downdoc -o docs/target/generated-docs/adminguide.md docs/src/diagram-replacer/generated-adocs/adminguide.adoc | |
| npx downdoc -o docs/target/generated-docs/arc42.md docs/src/diagram-replacer/generated-adocs/arc42.adoc | |
| npx downdoc -o docs/target/generated-docs/user-manual.md docs/src/diagram-replacer/generated-adocs/user-manual.adoc | |
| - name: MD files post-processing | |
| working-directory: docs/src/post-processing/ | |
| run: | | |
| export REPO=${GITHUB_REPOSITORY#*/} | |
| node fix_headers.js | |
| node fix_no_emphasis.js | |
| node fix_https_links.js | |
| node fix_relative_links.js https://$GITHUB_REPOSITORY_OWNER.github.io/$REPO/docs | |
| - name: MD linting | |
| run: | | |
| npm install markdownlint-cli2@0.11.0 | |
| npx markdownlint-cli2-config docs/.markdownlint.yaml docs/target/generated-docs/adminguide.md | |
| npx markdownlint-cli2-config docs/.markdownlint.yaml docs/target/generated-docs/arc42.md | |
| npx markdownlint-cli2-config docs/.markdownlint.yaml docs/target/generated-docs/user-manual.md | |
| - name: Move assets to target directory | |
| run: | | |
| mv docs/src/diagram-replacer/assets/ docs/target/generated-docs/assets/ | |
| - name: Generate Swagger UI | |
| uses: Legion2/swagger-ui-action@v1 | |
| with: | |
| output: swagger-ui | |
| spec-file: docs/api/traceability-foss-backend.json | |
| - name: Update documentation on GitHub Pages | |
| if: github.ref == 'refs/heads/main' | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: "./docs/target/generated-docs" | |
| destination_dir: "docs" | |
| - name: Deploy Swagger UI to GitHub Pages | |
| if: github.ref == 'refs/heads/main' | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: "swagger-ui" | |
| destination_dir: "docs/swagger-ui" |