diff --git a/.gitignore b/.gitignore index 28df974..30fc10d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ /build/* /images/* +node_modules/ +.cache/ diff --git a/CHANGELOG.md b/CHANGELOG.md index c604eca..573e984 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [5.0.0] - 2026-06-08 + +### Added +- `antora.yml` — Antora component descriptor at the repository root. Authors must update `name` and `title` to match their specification. +- `modules/ROOT/nav.adoc` — Antora navigation file defining the sidebar structure for the documentation site. +- `modules/ROOT/images` — Symlink to `docs-resources/images` so Antora can locate shared images within the module tree. +- `modules/ROOT/pages/` — Antora-standard content directory. All AsciiDoc source files moved here from `src/`. +- `antora-playbook.yml` — Local Antora playbook for previewing the specification as a multi-page HTML site via `make antora`. +- `antora` Makefile target — Builds a local Antora site to `build/site/`. Uses system `antora` or falls back to `npx antora`. +- `node_modules/` and `.cache/` added to `.gitignore` for Antora build artifacts. + +### Changed +- Moved all AsciiDoc source files and `example.bib` from `src/` to `modules/ROOT/pages/`. +- `Makefile` `SRC_DIR` updated from `src` to `modules/ROOT/pages`. +- `modules/ROOT/pages/spec-sample.adoc` — Updated `docs-resources` relative paths to reflect new depth within the Antora module tree, and updated `bibtex-file` path accordingly. + ## [4.0.0] - 2004-01-27 - Workflow improvements - Makefile refactoring diff --git a/Makefile b/Makefile index e8a3327..16b15ae 100644 --- a/Makefile +++ b/Makefile @@ -36,7 +36,7 @@ ifneq ($(SKIP_DOCKER),true) DOCKER_QUOTE := " endif -SRC_DIR := src +SRC_DIR := modules/ROOT/pages BUILD_DIR := build DOCS_PDF := $(DOCS:%.adoc=%.pdf) @@ -61,7 +61,7 @@ REQUIRES := --require=asciidoctor-bibtex \ --require=asciidoctor-lists \ --require=asciidoctor-mathematical -.PHONY: all build clean build-container build-no-container build-docs +.PHONY: all build clean build-container build-no-container build-docs antora all: build @@ -95,6 +95,18 @@ build-no-container: $(MAKE) SKIP_DOCKER=true build-docs @echo "Build completed successfully." +antora: + @echo "Building Antora site..." + @if command -v antora >/dev/null 2>&1; then \ + antora antora-playbook.yml; \ + elif command -v npx >/dev/null 2>&1; then \ + npx antora antora-playbook.yml; \ + else \ + echo "Antora not found. Install with: npm install -g antora"; \ + exit 1; \ + fi + @echo "Antora site built to build/site/" + # Update docker image to latest docker-pull-latest: ${DOCKER_BIN} pull ${DOCKER_IMG} diff --git a/antora-playbook.yml b/antora-playbook.yml new file mode 100644 index 0000000..ad2cf99 --- /dev/null +++ b/antora-playbook.yml @@ -0,0 +1,24 @@ +# Antora Playbook +# https://docs.antora.org/antora/latest/playbook/ +# +# Used by the `make antora` target to build the HTML site locally. +# For CI/CD, a separate playbook in your docs site repository will +# typically reference this component repository by URL. + +site: + title: RISC-V Specification + url: https://docs.riscv.org + start_page: spec-sample::spec-sample.adoc + +content: + sources: + - url: . + branches: HEAD + +ui: + bundle: + url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip + snapshot: true + +output: + dir: ./build/site diff --git a/antora.yml b/antora.yml new file mode 100644 index 0000000..9461675 --- /dev/null +++ b/antora.yml @@ -0,0 +1,12 @@ +# Antora Component Descriptor +# https://docs.antora.org/antora/latest/component-version-descriptor/ +# +# This file defines the Antora component for this RISC-V specification. +# Rename `name` and `title` to match your specification. + +name: spec-sample +title: RISC-V Example Specification (Zexmpl) +version: ~ + +nav: + - modules/ROOT/nav.adoc diff --git a/docs-resources b/docs-resources index 08bdece..3dd7194 160000 --- a/docs-resources +++ b/docs-resources @@ -1 +1 @@ -Subproject commit 08bdece421b2ed6741c709bfd8d2269b29dbf0b9 +Subproject commit 3dd7194c6694001d05e5c083ab606932b8eb72a7 diff --git a/modules/ROOT/images b/modules/ROOT/images new file mode 120000 index 0000000..470b1a9 --- /dev/null +++ b/modules/ROOT/images @@ -0,0 +1 @@ +../../docs-resources/images \ No newline at end of file diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc new file mode 100644 index 0000000..bd15326 --- /dev/null +++ b/modules/ROOT/nav.adoc @@ -0,0 +1,10 @@ +// Navigation file for Antora +// https://docs.antora.org/antora/latest/navigation/ +// +// Update this file to reflect your specification's chapter structure. + +* xref:spec-sample.adoc[RISC-V Example Specification] +** xref:intro.adoc[Introduction] +** xref:chapter2.adoc[The Second Chapter] +** xref:contributors.adoc[Contributors] +** xref:bibliography.adoc[Bibliography] diff --git a/modules/ROOT/pages/bibliography.adoc b/modules/ROOT/pages/bibliography.adoc new file mode 100644 index 0000000..4cc3eb7 --- /dev/null +++ b/modules/ROOT/pages/bibliography.adoc @@ -0,0 +1,4 @@ +[bibliography] +== Bibliography + +bibliography::[] diff --git a/modules/ROOT/pages/chapter2.adoc b/modules/ROOT/pages/chapter2.adoc new file mode 100644 index 0000000..856334b --- /dev/null +++ b/modules/ROOT/pages/chapter2.adoc @@ -0,0 +1,48 @@ +[[chapter2]] +== The Second Chapter + +. The first item. + +. The second item. ++ +.. The first sub item. + +.. The second sub item. ++ +[CAUTION] +==== +A moment of caution is required for this block of text must be read and apreciated for its importance. +==== + +. Yet another item. + +. Again, an item. + +.. A multi-line item. ++ +This item has multiple lines. ++ +By multiple lines, this is what we mean. ++ +Seriously, multiple. + +=== An example table + +.Nonsensical table +[cols="^1,^1,^1,^1,^3,^3",stripes=even,options="header"] +|=== +4+|Letters _and_ bits {set:cellbgcolor:green} 2+|A much longer area +|L|R|W|X|Quarter 1|Quarter 2 +|{set:cellbgcolor:!} 0|0|0|0 2+|Rows alternate colors +|0|0|0|1|Thing 1|Thing 2 +|1|0|0|0|Thing 3|Thing 4 +|1|1|1|1 2+|Span Thing 1 and 2 +|=== + +=== Sub section + +Diam donec adipiscing tristique risus indexterm:[risus]. Nisl rhoncus mattis rhoncus urna. Egestas egestas fringilla phasellus faucibus scelerisque eleifend donec pretium vulputate. Porta non pulvinar neque laoreet suspendisse interdum consectetur libero id. Massa vitae tortor condimentum lacinia quis vel. Donec ac odio tempor orci. Mi sit amet mauris commodo quis imperdiet massa tincidunt. Quis enim lobortis scelerisque fermentum dui. Lacus viverra vitae congue eu. Sed faucibus turpis in eu mi bibendum neque. Sit amet porttitor eget dolor. Aliquet eget sit amet tellus cras adipiscing enim. Id cursus metus aliquam eleifend mi. Vestibulum lorem sed risus ultricies tristique nulla aliquet. + +=== Yet another subsection + +Quam lacus suspendisse faucibus interdum posuere lorem ipsum. Nulla aliquet enim tortor at auctor urna nunc id cursus. Massa massa ultricies mi quis hendrerit dolor magna. Integer enim neque volutpat ac tincidunt. Dolor magna eget est lorem ipsum dolor. Urna neque viverra justo nec. Neque gravida in fermentum et. Fringilla ut morbi tincidunt augue interdum velit euismod. Dolor sit amet consectetur adipiscing elit. Eu facilisis sed odio morbi. In cursus turpis massa tincidunt dui. Orci indexterm:[orci] phasellus egestas tellus rutrum tellus. Semper eget duis at tellus at urna condimentum. Orci porta non pulvinar neque laoreet suspendisse interdum consectetur. diff --git a/modules/ROOT/pages/contributors.adoc b/modules/ROOT/pages/contributors.adoc new file mode 100644 index 0000000..13fd776 --- /dev/null +++ b/modules/ROOT/pages/contributors.adoc @@ -0,0 +1,7 @@ +== Contributors + +This RISC-V specification has been contributed to directly or indirectly by: + +[%hardbreaks] +* Author1 +* Author2 diff --git a/modules/ROOT/pages/example.bib b/modules/ROOT/pages/example.bib new file mode 100644 index 0000000..4c368b1 --- /dev/null +++ b/modules/ROOT/pages/example.bib @@ -0,0 +1,36 @@ +@inproceedings{riscI-isca1981, + title = {{RISC I}: {A} Reduced Instruction Set {VLSI} Computer}, + author = {David A. Patterson and Carlo H. S\'{e}quin}, + booktitle = {ISCA}, + location = {Minneapolis, Minnesota, USA}, + pages = {443-458}, + year = {1981} +} + +@inproceedings{Katevenis:1983, + author = {Manolis G.H. Katevenis and Robert W. Sherburne Jr. and David A. Patterson and Carlo H. S\'{e}quin}, + title = {The {RISC II} micro-architecture}, + booktitle = {Proceedings VLSI 83 Conference}, + year = {1983}, + month = {August} +} + +@inproceedings{Ungar:1984, + author = {David Ungar and Ricki Blau and Peter Foley and Dain Samples and David Patterson}, + title = {Architecture of {SOAR}: {Smalltalk} on a {RISC}}, + booktitle = {ISCA}, + address = {Ann Arbor, MI}, + year = {1984}, + pages = {188-197} +} + +@article{spur-jsscc1989, + author = {David D. Lee and Shing I. Kong and Mark D. Hill and George S. Taylor and David A. Hodges and Randy H. Katz and David A. Patterson}, + title = {A {VLSI} Chip Set for a Multiprocessor Workstation--{Part I}: An {RISC} Microprocessor with Coprocessor Interface and Support for Symbolic Processing}, + journal = {IEEE JSSC}, + year = {1989}, + volume = {24}, + number = {6}, + pages = {1688-1698}, + month = {December} +} diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..4abaca2 --- /dev/null +++ b/modules/ROOT/pages/index.adoc @@ -0,0 +1,2 @@ +[index] +== Index diff --git a/modules/ROOT/pages/intro.adoc b/modules/ROOT/pages/intro.adoc new file mode 100644 index 0000000..9b6292b --- /dev/null +++ b/modules/ROOT/pages/intro.adoc @@ -0,0 +1,43 @@ +[[intro]] +== Introduction + +Lorem ipsum indexterm:[Lorem ipsum] dolor sit amet, consectetur adipiscing elit, sed do *eiusmod tempor* incididunt ut labore et dolore magna aliqua. Felis imperdiet proin fermentum leo vel orci porta. Volutpat lacus laoreet non curabitur indexterm:[curabitur] gravida indexterm:[gravida]. Posuere urna nec tincidunt praesent semper feugiat nibh. Elit ``ullamcorper`` dignissim cras tincidunt lobortis. Malesuada fames ac turpis egestas integer eget. Tristique sollicitudin nibh sit amet commodo. Sed felis eget velit aliquet. Sit amet aliquam id diam maecenas ultricies mi. Consectetur purus ut faucibus pulvinar. Lectus urna duis convallis convallis tellus id. Fermentum iaculis eu non diam. Feugiat in fermentum posuere urna nec tincidunt praesent semper feugiat. Urna nec tincidunt praesent semper feugiat nibh. + +.Nonsensical code +[source, python] +---- +def banana_apple(): + x = "banana" + y = "apple" + for i in range(len(x)): + print(x[i], y[i]) + z = x + y + return z + +result = banana_apple() +print("Result:", result) +---- + +Commodo viverra maecenas accumsan lacus. Vulputate odio ut enim blandit indexterm:[blandit] volutpat maecenas volutpat blandit. Urna porttitor rhoncus dolor purus non. Tellus mauris a diam maecenas sed. Vitae auctor eu augue ut lectus. Ridiculus mus mauris vitae ultricies leo integer. Consequat semper viverra nam *libero* justo laoreet sit amet. Pellentesque pulvinar pellentesque habitant morbi tristique senectus et netus et. Ac placerat vestibulum lectus mauris ``ultrices`` eros in cursus turpis. Accumsan in nisl nisi scelerisque eu ultrices vitae. Cras ornare arcu dui vivamus. Vitae congue mauris rhoncus aenean. Consequat mauris nunc congue nisi vitae suscipit tellus. Tempus egestas sed sed risus pretium quam vulputate dignissim. Quis varius quam quisque id diam vel. Mattis nunc sed blandit libero volutpat sed cras ornare arcu. Amet mauris commodo quis imperdiet massa tincidunt nunc. + +[NOTE] +==== +The name RISC-V indexterm:[RISC-V] was chosen to represent the fifth major RISC ISA design from UC Berkeley (RISC-I cite:[riscI-isca1981], RISC-II cite:[Katevenis:1983], SOAR cite:[Ungar:1984], and SPUR cite:[spur-jsscc1989] were the first four). We also pun on the use of the Roman numeral "V" to signify "variations" and "vectors", as support for a range of architecture research, including various data-parallel accelerators, is an explicit goal of the ISA design. +==== + +=== Sub Section of Introduction + +Pellentesque habitant morbi *tristique* senectus et netus et. Aliquam purus sit amet luctus. Odio eu ``feugiat`` pretium nibh ipsum consequat nisl vel. Euismod lacinia at quis risus sed vulputate odio ut. Eu sem integer vitae justo eget. Cursus euismod quis viverra nibh. Tempus egestas sed sed risus. Quis imperdiet massa tincidunt nunc pulvinar. Id venenatis a condimentum vitae sapien pellentesque habitant. + +.Nonsensical wavedrom signals +[wavedrom, svg] +.... +{ + "signal": [ + { "name": "Clock", "wave": "P.......P" }, + { "name": "Data", "wave": "x.x..xx.x" }, + { "name": "Control", "wave": "0.1.01..0" }, + { "name": "Error", "wave": "zZzZzZzZz" } + ] +} +.... diff --git a/modules/ROOT/pages/spec-sample.adoc b/modules/ROOT/pages/spec-sample.adoc new file mode 100644 index 0000000..8caffef --- /dev/null +++ b/modules/ROOT/pages/spec-sample.adoc @@ -0,0 +1,78 @@ += RISC-V Example Specification Document (Zexmpl) +Authors: Author 1, Author 2 +include::../../../docs-resources/global-config.adoc[] +:docgroup: RISC-V Task Group +:description: RISC-V Example Specification Document (Zexmpl) +:revdate: 1/2023 +:revnumber: 1.0 +:revremark: This document is under development. Expect potential changes. Visit http://riscv.org/spec-state for further details. +:revinfo: +:preface-title: Preamble +:colophon: +:appendix-caption: Appendix +// https://docs.asciidoctor.org/asciidoc/latest/macros/images-directory/ +:imagesdir: ../../../docs-resources/images +:title-logo-image: image:risc-v_logo.png["RISC-V International Logo",pdfwidth=3.25in,align=center] +// Settings: +:experimental: +:reproducible: +//:WaveDromEditorApp: app/wavedrom-editor.app +:imagesoutdir: images +//:srcdir: src +:bibtex-file: modules/ROOT/pages/example.bib +:bibtex-order: alphabetical +:bibtex-style: apa +:icons: font +:lang: en +:listing-caption: Listing +:sectnums: +:toc: left +:toclevels: 4 +:source-highlighter: pygments +ifdef::backend-pdf[] +:source-highlighter: coderay +endif::[] +:data-uri: +:hide-uri-scheme: +:stem: latexmath +:footnote: +:xrefstyle: short + +[preface] +== List of figures +list-of::image[hide_empty_section=true, enhanced_rendering=true] + +[preface] +== List of tables +list-of::table[hide_empty_section=true, enhanced_rendering=true] + +[preface] +== List of listings +list-of::listing[hide_empty_section=true, enhanced_rendering=true] + +[WARNING] +.This document is in the link:http://riscv.org/spec-state[Development state] +==== +Expect potential changes. This draft specification is likely to evolve before +it is accepted as a standard. Implementations based on this draft +may not conform to the future standard. +==== + +[preface] +== Copyright and license information +This specification is licensed under the Creative Commons +Attribution 4.0 International License (CC-BY 4.0). The full +license text is available at +https://creativecommons.org/licenses/by/4.0/. + +Copyright 2025 by RISC-V International. + +[preface] +include::contributors.adoc[] + +include::intro.adoc[] +include::chapter2.adoc[] + +// The index must precede the bibliography +include::index.adoc[] +include::bibliography.adoc[]