Skip to content

Commit

Permalink
Merge pull request riscv#12 from rpsene/main
Browse files Browse the repository at this point in the history
Update the build process to use containers and add minor improvements
  • Loading branch information
rpsene authored Apr 20, 2023
2 parents 422ca9d + d2564b3 commit 4810a50
Show file tree
Hide file tree
Showing 5 changed files with 123 additions and 129 deletions.
83 changes: 23 additions & 60 deletions .github/workflows/build-pdf.yml
Original file line number Diff line number Diff line change
@@ -1,79 +1,42 @@
# This workflow installs dependencies for PDF generation, generates the PDF,
# and uploads the PDF as an artifact.

name: Build Document PDF
name: Build RISC-V Doc Spec Template

on:
workflow_dispatch:
push:
branches:
- main
pull_request:
branches:
- main
workflow_dispatch:
workflow_call:
outputs:
name:
description: "The base name of the pdf file (without .pdf extensions)"
value: ${{ jobs.build.outputs.name }}
pdf-name:
description: "The name of the pdf file (with .pdf extensions)"
value: ${{ jobs.build.outputs.pdf-name }}

jobs:
build:
runs-on: ubuntu-22.04

env:
NAME: example-spec
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
outputs:
name: ${{ steps.step1.outputs.name }}
pdf-name: ${{ steps.step2.outputs.pdf-name }}
runs-on: ubuntu-latest

steps:
- name: Set outputs.name
id: step1
run: echo "name=$NAME" >> $GITHUB_OUTPUT
- name: Set outputs.pdf-name
id: step2
run: echo "pdf-name=$NAME.pdf" >> $GITHUB_OUTPUT
# Checkout the repository
- name: Checkout repository
uses: actions/checkout@v3
with:
submodules: 'true'
- name: Install Ubuntu packages

# 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
- name: Pull Container
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@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@v3
with:
node-version: '16'
- name: Install Node.js dependencies
run: npm install ${NPM_PACKAGE_FOLDER}
- name: Generate PDF
docker pull riscvintl/riscv-docs-base-container-image:latest
# Build PDF file using the container
- name: Build Files
run: |
PATH=${PATH}:${BUNDLE_BIN}:$(npm bin) \
make
- name: Archive PDF result
docker run --rm -v ${{ github.workspace }}:/build riscvintl/riscv-docs-base-container-image:latest \
/bin/sh -c 'make'
# Set the short SHA for use in artifact names
- name: Set short SHA
run: echo "SHORT_SHA=$(echo ${GITHUB_SHA::7})" >> $GITHUB_ENV

# Upload the built PDF file as artifact
- name: Upload Build Artifact
uses: actions/upload-artifact@v3
with:
name: ${{ env.NAME }}.pdf
path: ${{ env.NAME }}.pdf
name: spec-sample-${{ env.SHORT_SHA }}.pdf
path: ${{ github.workspace }}/spec-sample.pdf
retention-days: 7
31 changes: 14 additions & 17 deletions .github/workflows/create-release.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,4 @@
# This work flow includes source and PDF in Release. It relies on the build-pdf workflow to create the PDF.
#
# NOTE: At this time it only runs manually.

name: Create Document Release
name: Create Release

on:
workflow_dispatch:
Expand All @@ -29,15 +25,16 @@ jobs:
runs-on: ubuntu-latest
needs: build
steps:
- name: Download Artifacts
uses: actions/download-artifact@v3
with:
name: ${{ needs.build.outputs.pdf-name }}
- name: Create Release
uses: softprops/action-gh-release@v1
with:
files: ${{ needs.build.outputs.pdf-name }}
tag_name: v${{ github.event.inputs.version }}
name: Release ${{ github.event.inputs.version }}
draft: ${{ github.event.inputs.draft }}
prerelease: ${{ github.event.inputs.prerelease }}
- name: Download Artifacts
uses: actions/download-artifact@v3
with:
name: ${{ needs.build.outputs.pdf-name }}
- name: Create Release
uses: softprops/action-gh-release@v1
with:
files: ${{ needs.build.outputs.pdf-name }}
tag_name: v${{ github.event.inputs.version }}
name: Release ${{ github.event.inputs.version }}
draft: ${{ github.event.inputs.draft }}
prerelease: ${{ github.event.inputs.prerelease }}
body: "This release includes the document in PDF format."
28 changes: 23 additions & 5 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,21 +1,39 @@
# 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.

HEADER_SOURCE := header.adoc
PDF_RESULT := example-spec.pdf
PDF_RESULT := spec-sample.pdf

ASCIIDOCTOR_PDF := asciidoctor-pdf
OPTIONS := --trace -a compress \
--attribute=mathematical-format=svg \
--attribute=pdf-fontsdir=docs-resources/fonts \
--attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \
-a mathematical-format=svg \
-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

all: build

build:
@echo "Building asciidoc"
$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)

clean:
rm $(PDF_RESULT)
@echo "Cleaning up generated files"
rm -f $(PDF_RESULT)

1 change: 0 additions & 1 deletion dependencies/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,2 @@
Dependencies for the build environment for various package managers. Used in
`.github/workflows/`.

109 changes: 63 additions & 46 deletions readme.adoc
Original file line number Diff line number Diff line change
@@ -1,70 +1,43 @@
= RISC-V docs-spec-template

This repository is used to prime GitHub repos for the RISC-V organization which will be used
to create specifications.
This repository serves as a template for creating GitHub repositories within the RISC-V organization that are intended for developing specifications.

**If you are reading this in a specification repo, please update the title for this section and
provide your introduction to your repository.**
**If you are reading this in a specification repository, please update the title for this section and provide a relevant introduction to your repository.**

= License
== 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.

= Contributors
== Contributors

Contributors to this specification are contained in the link:contributors.adoc[contributors] file.

For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRIBUTING] file.

= Dependencies
== Building the Document

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.
=== Building on Container

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:
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:

$ 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.

= Build the document from a container

To avoid dealing with configurations and dependencies, you can easily build this documentation from within a base container image which contains everything you need. Here are the steps:

NOTE: https://docs.docker.com/engine/install/[ensure you have Docker installed]
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 \
Expand All @@ -77,3 +50,47 @@ asciidoctor-pdf \
--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.

0 comments on commit 4810a50

Please sign in to comment.