-
Notifications
You must be signed in to change notification settings - Fork 20
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #13 from rpsene/main
Upgrade the build process
- Loading branch information
Showing
4 changed files
with
128 additions
and
153 deletions.
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |