From 296ec01f634f45d81e3afb22f9beca66b4cc6c96 Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Tue, 6 Jun 2023 16:41:50 -0300 Subject: [PATCH] Upgrade the build process * Add the capability to set revision mark * Add the capability to build on container or directly on the host using the Makefile * Fix the document layout to show all 8 pages * Enable CI for all PRs and Commits Signed-off-by: Rafael Sene --- .github/workflows/build-pdf.yml | 92 ++++++++++------------ Makefile | 38 +++++++-- header.adoc | 20 +++-- readme.adoc | 131 ++++++++++++-------------------- 4 files changed, 128 insertions(+), 153 deletions(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index 94372fd..1939dee 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -1,85 +1,73 @@ -name: Build Document PDF +name: Create Specification Document +# The workflow is triggered by pull request, push to main, and manual dispatch. on: workflow_dispatch: inputs: - release_type: - description: 'Release type (draft or regular)' - required: true - type: string - default: 'regular' version: description: 'Release version, e.g. X.Y.Z:' required: true type: string - target_branch: - description: 'Target branch to run the workflow on' - required: true - default: 'main' + revision_mark: + description: 'Set revision mark as Draft or Release:' + required: true + type: string + default: 'Draft' + prerelease: + 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: - branches: - - '*' push: branches: - - '*' + - main jobs: build: runs-on: ubuntu-latest steps: - # Checkout the repository + # Step 1: Checkout the repository - name: Checkout repository uses: actions/checkout@v3 + with: + submodules: 'recursive' - # Pull the latest RISC-V Docs container image - # https://github.com/riscv/riscv-docs-base-container-image - # https://hub.docker.com/r/riscvintl/riscv-docs-base-container-image + # Step 2: Pull the latest RISC-V Docs container image - name: Pull Container - run: | - docker pull riscvintl/riscv-docs-base-container-image:latest + run: docker pull riscvintl/riscv-docs-base-container-image:latest - # Build PDF file using the container + # Step 3: Build Files - name: Build Files - id: build_files - run: | - docker run --rm -v ${{ github.workspace }}:/build riscvintl/riscv-docs-base-container-image:latest \ - /bin/sh -c 'make' - - # Set the short SHA and repo name for use in artifact names - - name: Set short SHA and repo name - run: | - echo "SHORT_SHA=$(echo ${GITHUB_SHA::7})" >> $GITHUB_ENV - echo "REPO_NAME=$(echo ${GITHUB_REPOSITORY##*/})" >> $GITHUB_ENV + run: make + env: + VERSION: v${{ github.event.inputs.version }} + REVMARK: ${{ github.event.inputs.revision_mark }} - # Upload the built PDF files as individual artifacts + # Step 4: Upload the built PDF files as a single artifact - name: Upload Build Artifacts - run: | - for file in ${{ github.workspace }}/*.pdf; do - filename=$(basename "$file") - echo "Uploading $filename" - echo "ARTIFACT_NAME=$filename" >> $GITHUB_ENV - echo "ARTIFACT_PATH=$file" >> $GITHUB_ENV - done - - - name: Upload Artifact uses: actions/upload-artifact@v3 with: - name: ${{ env.ARTIFACT_NAME }} - path: ${{ env.ARTIFACT_PATH }} - retention-days: 7 - + name: Build Artifacts + path: ${{ github.workspace }}/*.pdf + retention-days: 30 + + # Create Release - name: Create Release - if: steps.build_files.outcome == 'success' && github.event_name == 'workflow_dispatch' && github.event.inputs.release_type != '' uses: softprops/action-gh-release@v1 with: - draft: ${{ github.event.inputs.release_type == 'draft' }} + files: ${{ github.workspace }}/*.pdf tag_name: v${{ github.event.inputs.version }} - name: ${{ env.CURRENT_DATE }} - body: | - This release was created by: ${{ github.event.sender.login }} - Release Notes: ${{ github.event.inputs.release_notes }} - files: | - ${{ github.workspace }}/*.pdf + name: Release ${{ github.event.inputs.version }} + draft: ${{ github.event.inputs.draft }} + prerelease: ${{ github.event.inputs.prerelease }} env: 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 8de65a5..ad48dfe 100644 --- a/Makefile +++ b/Makefile @@ -12,12 +12,22 @@ # 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 := header.adoc PDF_RESULT := spec-sample.pdf ASCIIDOCTOR_PDF := asciidoctor-pdf -OPTIONS := --trace -a compress \ +OPTIONS := --trace \ + -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 @@ -25,15 +35,31 @@ REQUIRES := --require=asciidoctor-bibtex \ --require=asciidoctor-diagram \ --require=asciidoctor-mathematical -.PHONY: all build clean +.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: - @echo "Cleaning up generated files" + @echo "Cleaning up generated files..." rm -f $(PDF_RESULT) - + @echo "Cleanup completed." \ No newline at end of file diff --git a/header.adoc b/header.adoc index 9c80801..5fb1282 100644 --- a/header.adoc +++ b/header.adoc @@ -1,25 +1,24 @@ = RISC-V Example Specification Document (Zexmpl) -Author 1; Author 2; RISC-V Task Group - -[[header]] +Authors: Author 1, Author 2 +:docgroup: RISC-V Task Group :description: RISC-V Example Specification Document (Zexmpl) :company: RISC-V.org :revdate: 1/2023 :revnumber: 1.0 -:revremark: This document is in development. Assume everything can change. See http://riscv.org/spec-state for details. +:revremark: This document is under development. Expect potential changes. Visit http://riscv.org/spec-state for further details. +:revinfo: :url-riscv: http://riscv.org :doctype: book :preface-title: Preamble :colophon: :appendix-caption: Appendix -:imagesdir: images +:imagesdir: docs-resources/images :title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] // Settings: :experimental: :reproducible: -// needs to be changed? bug discussion started //:WaveDromEditorApp: app/wavedrom-editor.app -:imagesoutdir: images +:imagesoutdir: docs-resources/images :bibtex-file: example.bib :bibtex-order: alphabetical :bibtex-style: apa @@ -39,13 +38,12 @@ endif::[] :footnote: :xrefstyle: short -// Preamble [WARNING] .This document is in the link:http://riscv.org/spec-state[Development state] ==== -Assume everything can change. This draft specification will change before -being accepted as standard, so implementations made to this draft -specification will likely not conform to the future standard. +Expect potential changes. This draft specification is likely to evolve before +it is accepted as a standard. Implementations based on this draft +may not conform to the future standard. ==== [preface] diff --git a/readme.adoc b/readme.adoc index d66fb5b..a88fe34 100644 --- a/readme.adoc +++ b/readme.adoc @@ -1,96 +1,59 @@ -= RISC-V docs-spec-template += RISC-V Specification Template -This repository serves as a template for creating GitHub repositories within the RISC-V organization that are intended for developing specifications. +This repository serves as a blueprint for creating GitHub repositories within the RISC-V organization for the purpose of developing specifications. The template aims to facilitate and standardize the process of specification development. -**If you are reading this in a specification repository, please update the title for this section and provide a relevant introduction to your repository.** +NOTE: If you are viewing this in a specification repository, kindly update the title for this section and provide an introduction relevant to your repository. == License -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. +This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the link:LICENSE[LICENSE] file. == Contributors -Contributors to this specification are contained in the link:contributors.adoc[contributors] file. +The list of contributors to this specification is maintained in the link:contributors.adoc[contributors] file. -For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRIBUTING] file. +For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUTING] file. == Building the Document -=== Building on Container - -To simplify the building process and avoid dealing with configurations and dependencies, you can build this documentation using a base container image, which contains everything you need. Follow these steps: - -Prerequisite: https://docs.docker.com/engine/install/[ensure you have Docker installed] - -1 - Clone the repository -``` -$ git clone https://github.com/riscv/docs-dev-guide.git -$ cd ./docs-dev-guide -``` -2 - Pull the RISC-V documentation base container image: -``` -$ docker pull riscvintl/riscv-docs-base-container-image:latest -``` -3 - Run the container and execute the build: -``` -$ docker run -it -v $(pwd)/docs-spec-template:/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'make' -``` -Output: -``` -Building asciidoc -asciidoctor-pdf \ - --attribute=mathematical-format=svg \ - --attribute=pdf-fontsdir=docs-resources/fonts \ - --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \ - --failure-level=ERROR \ - --require=asciidoctor-bibtex \ - --require=asciidoctor-diagram \ - --require=asciidoctor-mathematical \ - --out-file=example-spec.pdf \ - header.adoc -``` -4 - Clean -``` -docker run -it -v $(pwd):/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'make clean' -``` -=== Buidling on Local Machine - -==== 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. - -For more information on AsciiDoctor, specification guidelines, or building locally, see the -https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide]. - -==== Cloning the project - -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. - -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: - -``` -$ 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 -``` - -==== Building the document - -The final specification form of PDF can be generated using the `make` command. +=== Prerequisites + +To build the document, you'll need the following tools installed on your system: + +* Make +* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical +* Docker + +=== Clonning the Repository + +`git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git` + +=== Building the Documentation + +To start the build process, run `cd ./docs-spec-template && make build`. + +The Makefile script will check the availability of Docker on your system: + +* If Docker is available, the documentation will be built inside a Docker container using the image riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems. +* If Docker is not available, the documentation will be built directly on your system using the installed tools. + +The documentation is generated from the AsciiDoctor source files in your project. The primary source file is specified by the `HEADER_SOURCE` variable in the Makefile. + +The build process utilizes several options, including theming and font settings, and generates a PDF document as output. + +=== Cleaning up + +To clean up the generated files, run `make clean`. This will remove the generated PDF file. + +== Versioning + +The `VERSION` variable is used to specify the revision number for the generated documentation. The default revision number is "v0.0.0". + +== Customization + +You can customize the build process by modifying the following variables in the Makefile: + +* `DATE`: Specifies the revision date for the generated documentation. The default value is the current date. +* `REVMARK`: Specifies the revision remark for the generated documentation. The default value is "Draft". +* `PDF_RESULT`: Specifies the name of the output PDF file. +* `DOCKER_RUN`: Defines the Docker run command used when Docker is available. \ No newline at end of file