From c61318b5da6b2101b46b4023344097715c34f372 Mon Sep 17 00:00:00 2001 From: Baris Tanyeri <86656336+BarisTanyeri@users.noreply.github.com> Date: Tue, 22 Oct 2024 17:04:31 +0200 Subject: [PATCH] feat: initial implementation of antora site action --- .github/dependabot.yml | 18 +++ .github/workflows/ci.yml | 27 +++++ .github/workflows/release-please.yml | 18 +++ .github/workflows/test.yml | 29 +++++ .release-please-manifest.json | 3 + CONTRIBUTING.md | 106 ++++++++++++++++++ Dockerfile | 15 +++ LICENSE | 11 ++ MAINTAINERS.md | 4 + README.md | 93 ++++++++++++++- acceptance_test/playbook.yml | 12 ++ acceptance_test/portal/antora.yml | 5 + acceptance_test/portal/modules/ROOT/nav.adoc | 1 + .../portal/modules/ROOT/pages/index.adoc | 3 + acceptance_test/test.bats | 11 ++ action.yml | 34 ++++++ entrypoint.sh | 39 +++++++ release-please-config.json | 18 +++ 18 files changed, 445 insertions(+), 2 deletions(-) create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/release-please.yml create mode 100644 .github/workflows/test.yml create mode 100644 .release-please-manifest.json create mode 100644 CONTRIBUTING.md create mode 100644 Dockerfile create mode 100644 LICENSE create mode 100644 MAINTAINERS.md create mode 100644 acceptance_test/playbook.yml create mode 100644 acceptance_test/portal/antora.yml create mode 100644 acceptance_test/portal/modules/ROOT/nav.adoc create mode 100644 acceptance_test/portal/modules/ROOT/pages/index.adoc create mode 100644 acceptance_test/test.bats create mode 100644 action.yml create mode 100644 entrypoint.sh create mode 100644 release-please-config.json diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..4d76f21 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,18 @@ +--- +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: daily + groups: + minor-and-patch-action-updates: + update-types: + - minor + - patch + - package-ecosystem: docker + directory: / + schedule: + interval: daily + commit-message: + prefix: "feat(deps)" \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..7cc25f5 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,27 @@ +name: Image Build + +on: + push: + branches: [main] + pull_request: + types: [opened, synchronize, reopened] + +jobs: + build-and-publish: + runs-on: ubuntu-latest + steps: + - name: Checkout + id: git_checkout + uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1 + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@c47758b77c9736f4b2ef4073d4d51994fabfe349 # v3.7.1 + - name: Build the Action Image + id: docker_build + uses: docker/build-push-action@4f58ea79222b3b9dc2c8bbdd6debcef730109a75 # v6.9.0 + with: + push: false + context: . + file: ./Dockerfile + registry: ghcr.io + tags: | + ghcr.io/philips-software/antora-site-action:latest diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml new file mode 100644 index 0000000..0b065e1 --- /dev/null +++ b/.github/workflows/release-please.yml @@ -0,0 +1,18 @@ + on: + push: + branches: + - main + + permissions: + contents: write + pull-requests: write + + name: release-please + + jobs: + release-please: + runs-on: ubuntu-latest + steps: + - uses: googleapis/release-please-action@7987652d64b4581673a76e33ad5e98e3dd56832f # v4.1.3 + with: + token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..966d13b --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,29 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + types: [opened, synchronize, reopened] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout + id: git_checkout + uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1 + - name: Build playbook + uses: ./ + with: + antora_playbook: playbook.yml + site_sources_path: acceptance_test + - name: Setup Bats + id: setup-bats + uses: bats-core/bats-action@2104b40bb7b6c2d5110b23a26b0bf265ab8027db # v3.0.0 + - name: Test results + shell: bash + env: + BATS_LIB_PATH: ${{ steps.setup-bats.outputs.lib-path }} + TERM: xterm + run: bats acceptance_test/test.bats diff --git a/.release-please-manifest.json b/.release-please-manifest.json new file mode 100644 index 0000000..1772e6f --- /dev/null +++ b/.release-please-manifest.json @@ -0,0 +1,3 @@ +{ + ".": "1.0.0" +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b92234c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,106 @@ +# Contributing to antora-site-action + +First off, thank you for considering contributing to antora-site-action! 🎉đŸ’Ș + +Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests. + +## Contributing to development + +antora-site-action is a young open source project and we love to receive contributions from our community — you! There are many ways to contribute, from writing examples, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into antora-site-action itself. + +## Ground Rules + +* Be professional, respectful and considerate in your communication with others. +* Create issues for any major changes and enhancements that you wish to make. Discuss things transparently and get core-team feedback. + +## Your First Contribution + +### Introduction + +Submitting your first contribution (or Pull Request) can be scary, but we promise you it will be rewarding. Information on how to proceed can be found on numerous blog posts and websites. A small selection of beginner friendly tutorials: + +**Working on your first Pull Request?** You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github) + +**Contributing to open source for the first time can be scary and a little overwhelming.** Perhaps you’re a [Code Newbie](https://www.codenewbie.org/) or maybe you’ve been coding for a while but haven’t found a project you felt comfortable contributing to. [You can do it; here's how.](https://www.firsttimersonly.com/) + +#### Preparing your Fork + +1. Click ‘Fork’ on Github, creating e.g. yourname/antora-site-action. +2. Clone your project: ```git clone https://github.com/yourname/antora-site-action```. +3. ```cd antora-site-action```. +4. Create a branch: git checkout -b foo-the-bars 1.3. + +#### Making your Changes + +1. Write tests expecting the correct/fixed functionality; make sure they fail. +2. Implement functionality to make the test pass. +3. Run tests again, making sure they pass. +4. Add changelog entry briefly describing your change. +5. Commit your changes: git commit -m "Foo the bars" + +#### Creating Pull Requests + +1. Push your commit to get it back up to your fork: git push origin HEAD +2. Visit Github, click handy “Pull request” button that it will make upon noticing your new branch. +3. In the description field, write down issue number (if submitting code fixing an existing issue) or describe the issue + your fix (if submitting a wholly new bugfix). +4. Make sure that your pull request title adheres to [Conventional Commits]() +5. Hit ‘submit’. And please be patient - the maintainers will get to you when they can. + +#### Pull Request Title: Conventional Commits + +The title of your pull request should follow the style of [Conventional Commits](). Not only does this present a standardized categorization of the kind of work done on a pull request, but it also instructs the release workflow to increment the correct level of the version according to the rules of [Semantic Versioning](). + +The format of the title of the pull request is this: + + `[(optional scope)][!]: ` + +The `` of the pull request is one of these: + +* `feat:` adding new functionality +* `fix:` fixing a bug +* `test:` adding, improving, fixing micro and/or integration tests +* `ci:` modifications on how GitHub interacts with the archive: workflows and configuration files +* `doc:` anything documentation related +* `refactor:` refactoring code, including applying formatting +* `chore:` a catch-all type for any other commits + +An exclamation mark `!` is added to the type if the change is not backwards compatible. This should only be added to `feat` or `fix`. + +❗ **_NOTE:_** We do not enforce conventional commits for individual commit messages, only for the title of your pull request. + +â„č **_TIP:_** If your work consists of a single commit, creating a pull request will default to the name of that commit so if you use conventional commit style for that single commit, your pull request already has the correct name. + +Examples: + +* `feat: add support for plugin x` + + This pull request adds the 'plugin x' feature. + +* `fix!: broken component y` + + This pull request fixes 'component y', and indicates that this is a backwards-incompatible change. + +### Reviewing a Pull Request + +Anyone can review pull requests, we encourage others to review each other's work, however, only the maintainers can approve a pull request. +Pull Requests often require several approvals from maintainers, before being able to merge it. + +## How to report a vulnerability + +If you find a security vulnerability, do NOT open an issue. Email one of the [maintainers](MAINTAINERS.md) instead. + +In order to determine whether you are dealing with a security issue, ask yourself these two questions: + +* Can I access something that's not mine, or something I shouldn't have access to? +* Can I disable something for other people? + +If the answer to either of those two questions are "yes", then you're probably dealing with a security issue. Note that even if you answer "no" to both questions, you may still be dealing with a security issue, so if you're unsure, just email us. + +## How to report an issue + +When filing an issue, make sure to answer these five questions: + +1. What operating system and processor architecture are you using? +2. What did you do? +3. What did you expect to see? +4. What did you see instead? diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..c311271 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,15 @@ +# SPDX-License-Identifier: MIT +# Copyright (c) [2024] Koninklijke Philips N.V., https://www.philips.com + +FROM docker.io/antora/antora:3.1.9@sha256:8f0a966f89de687f6bd7278d4a198e944ed90b3e1f1bb9ee703f9f27784f060c +# Docker image for Antora documentation site generator (https://antora.org/) +# https://gitlab.com/antora/docker-antora + +COPY ./entrypoint.sh /entrypoint.sh + +# Add permissions to execute entrypoint +RUN chmod +x /entrypoint.sh +# install extra antora generators for documentation search and plantuml rendering +RUN npm i -g asciidoctor-plantuml asciidoctor-kroki @antora/lunr-extension + +ENTRYPOINT ["/entrypoint.sh"] diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..7564fdc --- /dev/null +++ b/LICENSE @@ -0,0 +1,11 @@ + MIT License + + Copyright © [2024] Koninklijke Philips N.V, + + Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +Source code for Antora - Docker Image can be found at https://gitlab.com/antora/docker-antora \ No newline at end of file diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..10ea147 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,4 @@ +# Maintainers + +Baris Tanyeri +Richard Peters diff --git a/README.md b/README.md index 944b35e..1587a8c 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,91 @@ -# antora-site-action -Antora Site Generator GitHub Action +# Antora Site GitHub Action + +[![Docker Image](https://github.com/philips-software/antora-site-action/workflows/Image%20Build/badge.svg)](https://github.com/philips-software/antora-site-action/actions) +[![Continuous Integration](https://github.com/philips-software/antora-site-action/workflows/CI/badge.svg)](https://github.com/philips-software/antora-site-action/actions) + +[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://choosealicense.com/licenses/mit/) + +GitHub action that can be used to generate the [Antora](https://antora.org/) site. + +Supported Antora version: *>= 3.0.0* + +Supported rendering plugins: *asciidoctor-plantuml*, *asciidoctor-kroki* + +Supported extensions: *@antora/lunr-extension* + +## Parameters + +The action accepts the following parameters: + +* `antora_playbook` -- that specifies the Antora playbook path within the repository +* `site_sources_path` -- the path within `$GITHUB_WORKSPACE` from where to run the site generation +* `antora_generator` -- Select antora generator for site +* `antora_custom_generator_dependencies` -- Enable installing Antora dependencies when using a custom generator +* `antora_additional_arguments` -- Pass customized arguments when running Antora + +## How to add this GitHub Action to your workflow + +``` yaml +name: "Generate site using antora site action" +uses: philips-software/antora-site-action@latest +with: + antora_playbook: antora-playbook.yml + # optional path within the repo, defaults to ${{github.workspace}} + site_sources_path: 'site-sources-folder' +``` + +## How to enable Lunr-extension for adding documentation search index + +Within your playbook file, define lunr-extension requirement + +``` yaml +antora: + extensions: + - require: '@antora/lunr-extension' +``` + +## Example: Complete site playbook example using extensions + +``` yaml +site: + title: Documentation Site + start_page: index.adoc +content: + sources: + - url: ../../ + branches: HEAD + start_path: documents/antora +ui: + bundle: + url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable + snapshot: true + supplemental_files: supplemental_ui # Custom UI folder, if you have one +antora: + extensions: + - require: "@antora/lunr-extension" +asciidoc: + attributes: + kroki-fetch-diagram: true # Enable fetching diagrams (UML etc..) + extensions: + - "asciidoctor-kroki" +``` + +## Changelog + +See [CHANGELOG](CHANGELOG.md) for more info on what's been changed. + +## Maintainers + +See [MAINTAINERS](MAINTAINERS.md) + +## Contributing + +[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org) + +antora-site-action uses semantic versioning and conventional commits. + +Please refer to our [CONTRIBUTING.md](CONTRIBUTING.md) guide when you want to contribute to this project. + +## License + +antora-site-action is licensed under the [MIT](https://choosealicense.com/licenses/mit/) license. See [LICENSE file](LICENSE). diff --git a/acceptance_test/playbook.yml b/acceptance_test/playbook.yml new file mode 100644 index 0000000..97d5739 --- /dev/null +++ b/acceptance_test/playbook.yml @@ -0,0 +1,12 @@ +site: + title: antora-site-action Integration Test + start_page: integration_test_portal::index.adoc +content: + sources: + - url: ../ + branches: HEAD + start_path: acceptance_test/portal +ui: + bundle: + url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable + snapshot: true diff --git a/acceptance_test/portal/antora.yml b/acceptance_test/portal/antora.yml new file mode 100644 index 0000000..69c4300 --- /dev/null +++ b/acceptance_test/portal/antora.yml @@ -0,0 +1,5 @@ +name: integration_test_portal +title: antora-site-action Integration Test +version: 1.0.0 # x-release-please-version +nav: + - modules/ROOT/nav.adoc diff --git a/acceptance_test/portal/modules/ROOT/nav.adoc b/acceptance_test/portal/modules/ROOT/nav.adoc new file mode 100644 index 0000000..057cbff --- /dev/null +++ b/acceptance_test/portal/modules/ROOT/nav.adoc @@ -0,0 +1 @@ +* xref:index.adoc[Introduction] \ No newline at end of file diff --git a/acceptance_test/portal/modules/ROOT/pages/index.adoc b/acceptance_test/portal/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..e854b09 --- /dev/null +++ b/acceptance_test/portal/modules/ROOT/pages/index.adoc @@ -0,0 +1,3 @@ += antora-site-action Integration Test + +This documentation is part of the integration test of the Antora site action diff --git a/acceptance_test/test.bats b/acceptance_test/test.bats new file mode 100644 index 0000000..65802a0 --- /dev/null +++ b/acceptance_test/test.bats @@ -0,0 +1,11 @@ +#!/usr/bin/env bats + +setup() { + bats_load_library bats-support + bats_load_library bats-assert +} + +@test "Successful test" { + run ls acceptance_test/build/site/index.html + assert_success +} diff --git a/action.yml b/action.yml new file mode 100644 index 0000000..14ced28 --- /dev/null +++ b/action.yml @@ -0,0 +1,34 @@ +name: "Antora Site" +description: "Generate the Antora site" +branding: + icon: book-open + color: yellow +inputs: + antora_playbook: + description: 'The Antora playbook file' + required: true + default: 'site.yaml' + site_sources_path: + description: 'The path relative to workspace root, where the asciidoc sources exits' + required: false + antora_generator: + description: 'Select generator to be used, currently supports the default "@antora/site-generator-default" or a custom generator path' + required: false + default: '@antora/site-generator-default' + antora_custom_generator_dependencies: + description: 'Enable installing Antora dependencies when using a custom generator' + required: false + default: 'false' + antora_additional_arguments: + description: 'Pass customized arguments when running Antora' + required: false + default: '' +runs: + using: 'docker' + image: 'Dockerfile' + args: + - ${{ inputs.antora_playbook}} + - ${{ inputs.site_sources_path }} + - ${{ inputs.antora_generator }} + - ${{ inputs.antora_custom_generator_dependencies }} + - ${{ inputs.antora_additional_arguments }} diff --git a/entrypoint.sh b/entrypoint.sh new file mode 100644 index 0000000..96a2abb --- /dev/null +++ b/entrypoint.sh @@ -0,0 +1,39 @@ +#!/bin/sh +# SPDX-License-Identifier: MIT +# Copyright (c) [2024] Koninklijke Philips N.V., https://www.philips.com + +set -eu +set -o pipefail + +echo "Using args: + src: $INPUT_SITE_SOURCES_PATH + playbook: $INPUT_ANTORA_PLAYBOOK + generator: $INPUT_ANTORA_GENERATOR + custom generator dependencies: $INPUT_ANTORA_CUSTOM_GENERATOR_DEPENDENCIES + additional arguments: $INPUT_ANTORA_ADDITIONAL_ARGUMENTS + " + +cd $GITHUB_WORKSPACE/$INPUT_SITE_SOURCES_PATH + +ls -ltr $GITHUB_WORKSPACE/$INPUT_SITE_SOURCES_PATH + +if [ "$INPUT_ANTORA_CUSTOM_GENERATOR_DEPENDENCIES" = true ] ; then + npm -g i @antora/asciidoc-loader \ + @antora/site-publisher \ + @antora/redirect-producer \ + @antora/site-mapper \ + @antora/ui-loader \ + @antora/page-composer \ + @antora/document-converter \ + @antora/content-classifier \ + @antora/playbook-builder \ + @antora/navigation-builder \ + @antora/content-aggregator \ + @antora/logger +fi + +NODE_PATH="$(npm -g root)" \ +antora \ +--generator $INPUT_ANTORA_GENERATOR \ +--fetch $INPUT_ANTORA_PLAYBOOK \ +--stacktrace $INPUT_ANTORA_ADDITIONAL_ARGUMENTS diff --git a/release-please-config.json b/release-please-config.json new file mode 100644 index 0000000..982a8ab --- /dev/null +++ b/release-please-config.json @@ -0,0 +1,18 @@ +{ + "include-component-in-tag": false, + "plugins": ["sentence-case"], + "packages": { + ".": { + "release-type": "simple", + "package-name": "antora-site-action", + "extra-files": [ + { + "type": "yaml", + "path": "acceptance_test/portal/antora.yml", + "jsonpath": "$.version" + } + ] + } + }, + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json" + }