New HPDcache User Guide in reStructuredText format

README.md

@@ -31,12 +31,10 @@ The HPDcache is an open-source High-Performance, Multi-requester, Out-of-Order L
 
 ## Documentation
 
-The HPDcache specification document can be found in the *docs/hpdcache_spec_document* folder.
-It is written in LaTeX.
-You cand find pre-compiled PDF documents in *docs/hpdcache_spec_document/release*.
+The HPDcache User Guide document can be found in the *docs* folder.
+It is written in reStructuredText format.
 
-If you need to recompile the specification document, a dedicated *Makefile* is in the specification folder.
-This *Makefile* needs the *latexmk* command-line tool (included in most common LaTeX distributions) and the *inkscape* tool to convert SVG images into PDF.
+If you need to compile the User Guide document, a dedicated *Makefile* is in the *docs* folder.
 
 
 ## Licensing

docs/LICENSE

@@ -0,0 +1,97 @@
+Solderpad Hardware License v2.1
+
+This license operates as a wraparound license to the Apache License
+Version 2.0 (the “Apache License”) and incorporates the terms and
+conditions of the Apache License (which can be found here:
+http://apache.org/licenses/LICENSE-2.0), with the following additions and
+modifications. It must be read in conjunction with the Apache License.
+Section 1 below modifies definitions and terminology in the Apache
+License and Section 2 below replaces Section 2 of the Apache License.
+The Appendix replaces the Appendix in the Apache License. You may, at
+your option, choose to treat any Work released under this license as
+released under the Apache License (thus ignoring all sections written
+below entirely).
+
+1. Terminology in the Apache License is supplemented or modified as
+follows:
+
+“Authorship”: any reference to ‘authorship’ shall be taken to read
+“authorship or design”.
+
+“Copyright owner”: any reference to ‘copyright owner’ shall be taken to
+read “Rights owner”.
+
+“Copyright statement”: the reference to ‘copyright statement’ shall be
+taken to read ‘copyright or other statement pertaining to Rights’.
+
+The following new definition shall be added to the Definitions section of
+the Apache License:
+
+“Rights” means copyright and any similar right including design right
+(whether registered or unregistered), rights in semiconductor
+topographies (mask works) and database rights (but excluding Patents and
+Trademarks).
+
+The following definitions shall replace the corresponding definitions in
+the Apache License:
+
+“License” shall mean this Solderpad Hardware License version 2.1, being
+the terms and conditions for use, manufacture, instantiation, adaptation,
+reproduction, and distribution as defined by Sections 1 through 9 of this
+document.
+
+“Licensor” shall mean the owner of the Rights or entity authorized by the
+owner of the Rights that is granting the License.
+
+“Derivative Works” shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent,
+as a whole, an original work of authorship or design. For the purposes of
+this License, Derivative Works shall not include works that remain
+reversibly separable from, or merely link (or bind by name) or physically
+connect to or interoperate with the Work and Derivative Works thereof.
+
+“Object” form shall mean any form resulting from mechanical
+transformation or translation of a Source form or the application of a
+Source form to physical material, including but not limited to compiled
+object code, generated documentation, the instantiation of a hardware
+design or physical object or material and conversions to other media
+types, including intermediate forms such as bytecodes, FPGA bitstreams,
+moulds, artwork and semiconductor topographies (mask works).
+
+“Source” form shall mean the preferred form for making modifications,
+including but not limited to source code, net lists, board layouts, CAD
+files, documentation source, and configuration files.
+
+“Work” shall mean the work of authorship or design, whether in Source or
+Object form, made available under the License, as indicated by a notice
+relating to Rights that is included in or attached to the work (an
+example is provided in the Appendix below).
+
+2. Grant of License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable license under the
+Rights to reproduce, prepare Derivative Works of, make, adapt, repair,
+publicly display, publicly perform, sublicense, and distribute the Work
+and such Derivative Works in Source or Object form and do anything in
+relation to the Work as if the Rights did not exist.
+
+APPENDIX
+
+Copyright 2023 CEA*
+*Commissariat a l'Energie Atomique et aux Energies Alternatives (CEA)
+
+SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+
+Licensed under the Solderpad Hardware License v 2.1 (the “License”); you
+may not use this file except in compliance with the License, or, at your
+option, the Apache License version 2.0. You may obtain a copy of the
+License at
+
+https://solderpad.org/licenses/SHL-2.1/
+
+Unless required by applicable law or agreed to in writing, any work
+distributed under the License is distributed on an “AS IS” BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,49 @@
+# Build instructions
+
+The documents in this directory are written in reStructuredText and compiled to HTML using Sphinx. For more information, check https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html.
+
+## Prerequisites
+
+This section outlines the necessary steps to build the document on Linux (tested on Debian-based distributions).
+
+Sphinx is based on Python and requires at least version 3.8. Additionally, `make` is required and can be installed through build-essential.
+
+```bash
+sudo apt update
+sudo apt install python3
+sudo apt install build-essential
+```
+
+Please verify your Python version using
+
+```bash
+python3 --version
+```
+
+Sphinx requires certain packages to build these documents. These are listed in `requirements.txt`. They can be installed using
+
+```bash
+pip install -r requirements.txt
+```
+
+## Building the documents
+
+Build is invoked via the `make` command. Typically, an HTML should be build.
+
+```bash
+make html
+```
+
+A secondary build target is pdf. To build the pdf, additional prerequisites need to be met. To install `pdflatex`, run
+
+```bash
+sudo apt-get install texlive-latex-base
+```
+
+A pdf document can be built using the command
+
+```bash
+make latexpdf
+```
+
+Simply type `make` to view other available targets.

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinx-rtd-theme

docs/source/_static/theme_overrides.css

@@ -0,0 +1,9 @@
+/* override table width restrictions */
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}
+.wy-table-responsive {
+    margin-bottom: 24px;
+    max-width: 100%;
+    overflow: visible;
+}