= 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 https://github.com/riscv/docs-templates/blob/main/local_build.md[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 https://github.com/riscv/riscv-docs-base-container-image[here].

== Build a PDF Using GitHub actions

=== Build this repo's example.pdf using github actions

. Navigate to https://github.com/riscv/docs-templates/actions/workflows/build-pdf.yml[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.
