RISC-V Documentation Developer Guide

This repo contains:

A demo that can be used for you to implement Github actions to build pdfs for RISC-V documentation.
A docs-dev-guide.pdf file that contains helpful information to assist documentation contributors in their authorship.
A robust, but not complete, list of Asciidoctor features that might be used in RISC-V docs. See the asciidoctor docs for a complete list.

A simple template for writing a RISC-V specification based off this developer guide can be found here: https://github.com/riscv/docs-spec-template

The Github actions build requires that you keep specific assets in the same relative locations for the build to work properly, because it pulls in information that contains required images, fonts, themes, page formatting, bibtex, and other assets.

Cloning this repo gives you the file structure that you need for creating professional quality pdfs from AsciiDoc, along with the example.pdf that demonstrates how to handle use cases that we have encountered.

Note	This is a work in progress, and the tools can change, so please email help@riscv.org if you run into problems and/or have questions.

Tip	While we ask that all RISC-V contributors keep the established look and feel that you can see in the output from this repo, you can request consideration for changes. A group or committee and a process for considering change requests is likely to form in 2022,

Build a PDF locally

Instructions for building locally can be found in local_build.md.

Build a PDF using a Docker container

You can easily build the documentation by leveraging a pre-built container image with all dependencies already installed. Follow the steps here.

Build a PDF Using GitHub actions

Build this repo’s example.pdf using github actions

Navigate to github actions for this repo.
Click the Build Document PDF button.
In the Run workflow dropdown that displays, click the down arrow, then click the green Run workflow button in the list.

The build starts running and its progress displays in the list.

Github actions indicates a successful build with a green button, or an unsuccessful build with a red button.

Note	If problems arise with the build, let us know by emailing help@riscv.org.

Integrate this build into an existing repo

Some RISC-V contributors are linking directly to the resources directory within this docs-templates repo. While this is a good idea from the point of view of seamlessly syncing with any style changes that take place over time, this does not give you all of the assets that contribute to the look and feel of RISC-V documentation.

The reason is that the look and feel of PDF output from the toolchain in use is controlled by interactions between the Github actions build commands (contained in files within .github/workflows and /dependencies) and:

AsciiDoc headers (here in book_header.adoc).
Graphics files (here in /images and its subdirectories).
a YAML theme file (here in /resources/themes).
fonts (here in /resources/fonts).
defaults used by Asciidoctor in Prawn.

While best practice is usually to maintain the same relative locations for files and directories so that other contributors can easily find everything, you have the option of changing things for your group and editing the github actions for your repo—as long as the pdf output keeps the established look and feel.

We use the modifier usually because AsciiDoc is intentionally used because of its usefulness in automated environments.