diff --git a/readme.html b/readme.html new file mode 100644 index 0000000..6ab4a62 --- /dev/null +++ b/readme.html @@ -0,0 +1,578 @@ + + + + + + + +RISC-V Specification Template + + + + + +
+
+
+
+

This repository serves as a template for creating GitHub repositories within the RISC-V organization for the purpose of developing specifications. It 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

+
+
+

Directory Structure

+
+
    +
  • +

    dependencies/: software dependencies needed to build the specification

    +
    • +
  • +

    docs-resources/: resources for all specifications sourced from git submodule

    +
    • +
  • +

    src/: source files for the specification

    +
    • +
  • +

    build/: default directory where the build artifacts are generated

    +
    • +
+
+
+
+

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

    +
    • +
+
+
+
+

Cloning 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
+
+
+
+
+
+
+ + + diff --git a/example.bib b/src/example.bib similarity index 100% rename from example.bib rename to src/example.bib diff --git a/src/header.adoc b/src/header.adoc index 53e3e07..5419bf1 100644 --- a/src/header.adoc +++ b/src/header.adoc @@ -20,7 +20,8 @@ Authors: Author 1, Author 2 :reproducible: //:WaveDromEditorApp: app/wavedrom-editor.app :imagesoutdir: ../build/images -:bibtex-file: example.bib +:srcdir: src +:bibtex-file: {srcdir}/example.bib :bibtex-order: alphabetical :bibtex-style: apa :icons: font