From 3e4767b4ad8783b74fb6d46bacec1718007cea0d Mon Sep 17 00:00:00 2001 From: Kevin Broch Date: Tue, 23 Jan 2024 10:44:23 -0800 Subject: [PATCH] Add directory structure description to readme related to #26 other minor edits: * minor wording changes * add line spacing between blocks * add `shell` to code blocks Signed-off-by: Kevin Broch --- readme.adoc | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/readme.adoc b/readme.adoc index c4af2da..68f2461 100644 --- a/readme.adoc +++ b/readme.adoc @@ -1,6 +1,6 @@ = 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. +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. @@ -16,26 +16,38 @@ For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUT == Building the Document +=== Directory Structure + +The following directories are used to organize the contents of this repo: + +* `dependencies/`: software dependencies needed to build the specification +* `docs-resources/`: resources for all specifications sourced from link:.gitmodules[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 +* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical * Docker === Cloning the Repository -``` + +```shell git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git ``` + === Building the Documentation To start the build process, run: -``` + +```shell cd ./docs-spec-template && make build ``` -The Makefile script will check the availability of Docker on your system: +The link: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. @@ -47,7 +59,7 @@ The build process utilizes several options, including theming and font settings, === Cleaning up To clean up the generated files, run: -``` + +```shell make clean ``` -This will remove the generated PDF file.