Skip to content

riscv/docs-spec-template

Repository files navigation

RISC-V Specification Template

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.

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). For details, see the LICENSE file.

Contributors

The list of contributors to this specification is maintained in the contributors file.

For guidelines on how to contribute, refer to the CONTRIBUTING file.

Building the Document

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

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.