diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index 242eec7..57cc750 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -1,88 +1,72 @@ -# This workflow installs dependencies for PDF generation, generates the PDF, -# and uploads the PDF as an artifact. - -name: Build Document PDF +name: Create Specification Document +# The workflow is triggered by pull request, push to main, and manual dispatch. on: - push: - branches: - - main - pull_request: - branches: - - main workflow_dispatch: inputs: + version: + description: 'Release version, e.g. X.Y.Z:' + required: true + type: string + revision_mark: + description: 'Set revision mark as Draft, Release or Stable:' + required: true + type: string + default: 'Draft' prerelease: - description: 'Generate a pre-release.' - required: false + description: 'Tag as a pre-release?' + required: false + type: boolean + default: true + draft: + description: 'Create release as a draft?' + required: false type: boolean + default: false + pull_request: + push: + branches: + - main jobs: build: runs-on: ubuntu-latest - env: - APT_PACKAGES_FILE: ${{ github.workspace }}/dependencies/apt_packages.txt - BUNDLE_GEMFILE: ${{ github.workspace }}/dependencies/Gemfile - BUNDLE_BIN: ${{ github.workspace }}/bin - NPM_PACKAGE_FOLDER: ${{ github.workspace }}/dependencies steps: + # Step 1: Checkout the repository - name: Checkout repository - uses: actions/checkout@v2 - with: - submodules: 'true' - - name: Install Ubuntu packages - run: | - sudo apt-get update - grep -vE '^#' ${APT_PACKAGES_FILE} | xargs sudo apt-get install --yes --no-install-recommends - # Ruby for asciidoctor - - name: Setup Ruby and Gemfile content - uses: ruby/setup-ruby@v1 - with: - ruby-version: "3.2.0" - bundler-cache: true - # Node.js for wavedrom - - uses: actions/cache@v2 + uses: actions/checkout@v3 with: - path: ~/.npm - key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} - restore-keys: | - ${{ runner.os }}-node- - - name: Setup Node.js - uses: actions/setup-node@v2 - with: - node-version: '14' - - name: Install Node.js dependencies - run: npm install ${NPM_PACKAGE_FOLDER} - - name: Generate PDF - run: | - PATH=${PATH}:${BUNDLE_BIN}:$(npm bin) \ - make - - name: Archive PDF result - uses: actions/upload-artifact@v2 + submodules: 'recursive' + + # Step 2: Pull the latest RISC-V Docs container image + - name: Pull Container + run: docker pull riscvintl/riscv-docs-base-container-image:latest + + # Step 3: Build Files + - name: Build Files + run: make + env: + VERSION: v${{ github.event.inputs.version }} + REVMARK: ${{ github.event.inputs.revision_mark }} + + # Step 4: Upload the built PDF files as a single artifact + - name: Upload Build Artifacts + uses: actions/upload-artifact@v3 with: - name: riscv-cfi.pdf - path: riscv-cfi.pdf - retention-days: 7 + path: ${{ github.workspace }}/*.pdf + retention-days: 30 + + # Create Release - name: Create Release - id: create_release - if: ${{ github.event.inputs.prerelease }} - uses: actions/create-release@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + uses: softprops/action-gh-release@v1 with: - tag_name: ${{ github.ref_name }} - release_name: Release ${{ github.ref_name }} - draft: false - prerelease: true - - name: Upload Release Asset - id: upload-release-asset - if: ${{ github.event.inputs.prerelease }} - uses: actions/upload-release-asset@v1 + files: ${{ github.workspace }}/*.pdf + tag_name: v${{ github.event.inputs.version }} + name: Release ${{ github.event.inputs.version }} + draft: ${{ github.event.inputs.draft }} + prerelease: ${{ github.event.inputs.prerelease }} env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - upload_url: ${{ steps.create_release.outputs.upload_url }} - asset_path: ./riscv-cfi.pdf - asset_name: riscv-cfi.pdf - asset_content_type: application/pdf + GITHUB_TOKEN: ${{ secrets.GHTOKEN }} + if: github.event_name == 'workflow_dispatch' + # This condition ensures this step only runs for workflow_dispatch events. diff --git a/Makefile b/Makefile index 0b7cdf3..0adbd4a 100644 --- a/Makefile +++ b/Makefile @@ -1,21 +1,65 @@ +# Makefile for RISC-V Doc Template +# +# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 +# International License. To view a copy of this license, visit +# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to +# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. +# +# SPDX-License-Identifier: CC-BY-SA-4.0 +# +# Description: +# +# This Makefile is designed to automate the process of building and packaging +# the Doc Template for RISC-V Extensions. + +DATE ?= $(shell date +%Y-%m-%d) +VERSION ?= v0.0.0 +REVMARK ?= Draft +DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ +riscvintl/riscv-docs-base-container-image:latest + HEADER_SOURCE := cfi_header.adoc PDF_RESULT := riscv-cfi.pdf ASCIIDOCTOR_PDF := asciidoctor-pdf OPTIONS := --trace \ - --attribute=mathematical-format=svg \ - --attribute=pdf-fontsdir=docs-resources/fonts \ - --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \ + -a compress \ + -a mathematical-format=svg \ + -a revnumber=${VERSION} \ + -a revremark=${REVMARK} \ + -a revdate=${DATE} \ + -a pdf-fontsdir=docs-resources/fonts \ + -a pdf-style=docs-resources/themes/riscv-pdf.yml \ --failure-level=ERROR REQUIRES := --require=asciidoctor-bibtex \ --require=asciidoctor-diagram \ --require=asciidoctor-mathematical - + +.PHONY: all build clean build-container build-no-container + all: build -build: - @echo "Building asciidoc" +build: + @echo "Checking if Docker is available..." + @if command -v docker &> /dev/null ; then \ + echo "Docker is available, building inside Docker container..."; \ + $(MAKE) build-container; \ + else \ + echo "Docker is not available, building without Docker..."; \ + $(MAKE) build-no-container; \ + fi + +build-container: + @echo "Starting build inside Docker container..." + $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" + @echo "Build completed successfully inside Docker container." + +build-no-container: + @echo "Starting build..." $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) - + @echo "Build completed successfully." + clean: - rm $(PDF_RESULT) + @echo "Cleaning up generated files..." + rm -f $(PDF_RESULT) + @echo "Cleanup completed." diff --git a/readme.adoc b/readme.adoc index 97e2d16..38ae596 100644 --- a/readme.adoc +++ b/readme.adoc @@ -12,48 +12,35 @@ instructions. = License -This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). -See the https://github.com/riscv/docs-spec-template/blob/main/LICENSE[LICENSE] file for details. +This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). +See the link:LICENSE[LICENSE] file for details. = Contributors -Contributors to this specification are contained in the -https://github.com/riscv/docs-spec-template/blob/main/contributors.adoc[contributors.adoc] file. +Contributors to this specification are contained in the link:contributors.adoc[contributors] file. -For instructions on how to contribute please see the -https://github.com/riscv/docs-spec-template/blob/main/CONTRIBUTING.md[CONTRIBUTING] file. +For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRIBUTING] file. = Dependencies -This project is built using AsciiDoctor (Ruby). The repository has been setup to build the PDF on -checkin using GitHub actions. Workflow dependencies are located in the `dependencies` directory. +To build the document, you'll need the following tools installed on your system: -For more information on AsciiDoctor, specification guidelines, or building locally, see the -https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide]. +``` + Make + asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical + Docker +``` -= Cloning the project += Cloning and Building the Document -This project uses https://git-scm.com/book/en/v2/Git-Tools-Submodules[GitHub Submodules] -to include the https://github.com/riscv/docs-resources[RISC-V docs-resources project] -to achieve a common look and feel. +This project uses submodules to include the RISC-V documentation toolchain. -When cloning this repository for the first time, you must either use -`git clone --recurse-submodules` or execute `git submodule init` and `git submodule update` after the clone to populate the docs-resources directory. Failure to clone the submodule, will result -in the PDF build fail with an error message like the following: +``` + git clone --recurse-submodule https://github.com/riscv/riscv-cfi.git + cd ./riscv-zacas.git + make VERSION=v1.0.0 REVMARK=Draft +``` - $ make - asciidoctor-pdf \ - -a toc \ - -a compress \ - -a pdf-style=docs-resources/themes/riscv-pdf.yml \ - -a pdf-fontsdir=docs-resources/fonts \ - --failure-level=ERROR \ - -o profiles.pdf profiles.adoc - asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme - No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts - Use --trace for backtrace - make: *** [Makefile:7: profiles.pdf] Error 1 +`VERSION`: Represents the version of the specification being built. By default, this is set to 'v0.0.0'. You can change this to a different value, like 'v1.0.0', 'v1.1.0', etc., based on the current version of your specification. -= Building the document - -The final specification form of PDF can be generated using the `make` command. +`REVMARK`: This represents a revision marker for the project. Its default value is 'Draft'. You may want to change this to something like 'Release', 'Stable' or 'Ratified'. \ No newline at end of file diff --git a/riscv-cfi.pdf b/riscv-cfi.pdf deleted file mode 100644 index 99f67c4..0000000 Binary files a/riscv-cfi.pdf and /dev/null differ