diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..f0c2967 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,2 @@ +# RISC-V Code of Conduct +All RISC-V International projects are governed by the RISC-V Code of Conduct found at https://riscv.org/community/community-code-of-conduct/. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1d98c72 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,58 @@ +# Contribution Guidelines + +As an open-source project, we appreciate and encourage community members to submit patches directly to the project. To maintain a well-organized development environment, we have established standards and methods for submitting changes. This document outlines the process for submitting patches to the project, ensuring that your contribution is swiftly incorporated into the codebase. + +# Licensing + +Licensing is crucial for open-source projects, as it guarantees that the software remains available under the conditions specified by the author. + +This project employs the Creative Commons Attribution 4.0 International license, which can be found in the LICENSE file within the project's repository. + +Licensing defines the rights granted to you as an author by the copyright holder. It is essential for contributors to fully understand and accept these licensing rights. In some cases, the copyright holder may not be the contributor, such as when the contributor is working on behalf of a company. + +# Developer Certificate of Origin (DCO) +To uphold licensing criteria and demonstrate good faith, this project mandates adherence to the Developer Certificate of Origin (DCO) process. + +The DCO is an attestation appended to every contribution from each author. In the commit message of the contribution (explained in greater detail later in this document), the author adds a Signed-off-by statement, thereby accepting the DCO. + +When an author submits a patch, they affirm that they possess the right to submit the patch under the designated license. The DCO agreement is displayed below and at https://developercertificate.org. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b), or (c), and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + +# DCO Sign-Off Methods +The DCO necessitates the inclusion of a sign-off message in the following format for each commit within the pull request: + +Signed-off-by: Stephano Cetola + +Please use your real name in the sign-off message. + +You can manually add the DCO text to your commit body or include either -s or --signoff in your standard Git commit commands. If you forget to incorporate the sign-off, you can also amend a previous commit with the sign-off by executing git commit --amend -s. If you have already pushed your changes to GitHub, you will need to force push your branch afterward using git push -f. + +Note: + +Ensure that the name and email address associated with your GitHub account match the name and email address in the Signed-off-by line of your commit message. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..651404c --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,8 @@ +# Governance +This project for the template specification is governed by the Documentation SIG. + +The group can be joined by RISC-V members at: https://lists.riscv.org/g/sig-documentation. + +Mailing list archives are available at: https://lists.riscv.org/g/sig-documentation/topics. + +**_NOTE:_** PROJECTS BUILT USING THE TEMPLATE SHOULD UPDATE THE ABOVE TEXT AS-NEEDED. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..6fc05bc --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,5 @@ +# Maintainers + +This project is maintained by the following people: + +- diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..aa68692 --- /dev/null +++ b/README.adoc @@ -0,0 +1,111 @@ += RISC-V Documentation Developer Guide + +This repo contains useful information for using AsciiDoc to write RISC-V specifications. + +A simple template for beginning a RISC-V specification can be found here: https://github.com/riscv/docs-spec-template + +== License + +This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the link:LICENSE[LICENSE] file. + +== Maintainers + +The list of maintainers of this repo is maintained in the link:MAINTAINERS.md[MAINTAINERS] file. + +== Contributors + +The list of contributors to this document is maintained in the link:src/contributors.adoc[contributors] file. + +For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUTING] file. + +== Governance + +The governance for this project is defined in the link:GOVERNANCE.md[GOVERNANCE] file. + +Community information, including meeting (if held) and mailing lists are detailed in this file. + +== 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 +* Docker + +=== Cloning the Repository + +```shell +git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git +``` + +All in one single line: + +```shell +git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git && cd docs-spec-template && git submodule update --init --recursive + +``` + +=== Building the Documentation + +To start the build process, run: + +```shell +cd ./docs-spec-template && make build +``` + +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. + +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: + +```shell +make clean +``` + +== Enabling pre-commit checks locally + +The repository has some basic commit checks set up with https://pre-commit.com/[pre-commit] that will be enforced by the GitHub CI. +To ensure these checks are also run in the local repository while making changes the following can be done: + +.Installing pre-commit tool +[source,shell] +---- +# Do once on your system +pip3 install pre-commit +---- + +.Installing pre-commit git hook in repo +[source,shell] +---- +# Do once in local repo +pre-commit install +---- + +Rather than doing the above `pre-commit install` in every repo that uses it, you can do it https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories[once on your system.] + +When enabling additional checks https://pre-commit.com/#plugins[by editing .pre-commit-config.yaml], it is recommended running the newly added check on all files in the repository. This can be done with the following command: + +.Running all pre-commit hooks on all files +[source,shell] +---- +pre-commit run --all-files +---- diff --git a/docs-resources b/docs-resources index 66f972d..35203a4 160000 --- a/docs-resources +++ b/docs-resources @@ -1 +1 @@ -Subproject commit 66f972d7dc961551a7815d2fceb82fbea7ce2c44 +Subproject commit 35203a4f123d0be162b6b5ea213a657b594f8c36 diff --git a/images/ethane.svg b/images/ethane.svg deleted file mode 100644 index 347471b..0000000 --- a/images/ethane.svg +++ /dev/null @@ -1,90 +0,0 @@ - - - -ethane - - - -C_0 - -C_0 - - - -H_0 - -H_0 - - - -C_0--H_0 - - - - -H_1 - -H_1 - - - -C_0--H_1 - - - - -H_2 - -H_2 - - - -C_0--H_2 - - - - -C_1 - -C_1 - - - -C_0--C_1 - - - - -H_3 - -H_3 - - - -C_1--H_3 - - - - -H_4 - -H_4 - - - -C_1--H_4 - - - - -H_5 - -H_5 - - - -C_1--H_5 - - - - diff --git a/images/litmus_sample.png b/images/litmus_sample.png deleted file mode 100644 index ea5f37c..0000000 Binary files a/images/litmus_sample.png and /dev/null differ diff --git a/images/test-diagram.svg b/images/test-diagram.svg deleted file mode 100644 index 910b60e..0000000 --- a/images/test-diagram.svg +++ /dev/null @@ -1,77 +0,0 @@ - - - -G - - - -eiid0 -a: Ry=1 - - - -eiid1 -c: Wx=t - - - -eiid0->eiid1 - - - -fence -ppo - - - -eiid2 -d: Rx=t - - - -eiid1->eiid2 - - -rf - - - -eiid3 -e: Rt=$v$ - - - -eiid2->eiid3 - - -addr -ppo - - - -eiid4 -f: Wy=1 - - - -eiid2->eiid4 - - -ppo - - - -eiid3->eiid4 - - -po - - - -eiid4->eiid0 - - -rf - - - diff --git a/images/z-type.svg b/images/z-type.svg deleted file mode 100644 index 6069bb9..0000000 --- a/images/z-type.svg +++ /dev/null @@ -1 +0,0 @@ -067111214151920242531opcoderdfunc3rs1rs2funct7z-Type \ No newline at end of file diff --git a/readme.adoc b/readme.adoc deleted file mode 100644 index 30d6833..0000000 --- a/readme.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= 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. diff --git a/src/additionaltext.adoc b/src/additionaltext.adoc index a450f5c..82bc4f0 100644 --- a/src/additionaltext.adoc +++ b/src/additionaltext.adoc @@ -7,4 +7,4 @@ I'm testing some things Does this xref:writing.adoc[link work]? -How about xref:writing.adoc#writing.adoc[this one]? +How about xref:writing.adoc#writing.adoc[this one]? diff --git a/src/authoring.adoc b/src/authoring.adoc index 7bca43d..4316ab9 100644 --- a/src/authoring.adoc +++ b/src/authoring.adoc @@ -61,4 +61,3 @@ The following list contains links to resources for text editors/IDEs support of ==== included text include::additionaltext.adoc[] - diff --git a/src/contributors.adoc b/src/contributors.adoc new file mode 100644 index 0000000..13fd776 --- /dev/null +++ b/src/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/src/graphics.adoc b/src/graphics.adoc index c38205d..338f287 100644 --- a/src/graphics.adoc +++ b/src/graphics.adoc @@ -572,5 +572,3 @@ The second test {bits: 3, name: 'funct3', type: 8, attr: ['3', 'C.SW','C.SD','C.SQ','C.FSW','C.FSD']}, ], config: {bits: 16}} .... - - diff --git a/src/writing.adoc b/src/writing.adoc index a03d386..056c365 100644 --- a/src/writing.adoc +++ b/src/writing.adoc @@ -6,10 +6,10 @@ Follow these tips to write your documents well. [[simple-concise]] === Write simply and concisely -Keep your writing as simple as possible. +Keep your writing as simple as possible. -* Use as few words as possible without sounding too formal or too casual. -* Shorten or simplify long sentences or else break them into separate sentences. +* Use as few words as possible without sounding too formal or too casual. +* Shorten or simplify long sentences or else break them into separate sentences. * Use lists to make the content more scannable. [[international-audience]] @@ -49,4 +49,3 @@ I have a list of existing guides that we can use as a starting point. These are * https://developers.google.com/style[Google's developer docs style guide] * https://stylepedia.net/style/[Stylepedia] * https://docs.netapp.com/us-en/contribute/style.html#write-conversationally[NetApp styke guide] -