Merge pull request #138 from NXP/feature/prepare-documentation

Feature/prepare documentation

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# Copyright 2023 OpenHW Group
+# Solderpad Hardware License, Version 2.1, see LICENSE.md for details.
+# SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.9"
+
+# Build from the docs directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+
+# Explicitly set the Python requirements
+python:
+  install:
+    - requirements: doc/requirements.txt

doc/Readme.md

@@ -0,0 +1,45 @@
+# CVE2 Documentation
+
+The documentation of CVE2 is 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
+
+To build the documentation, certain prequisites need to be fulfilled. This section outlines the necessary steps on Linux. Tested on Ubuntu 20.04.
+
+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
+```
+
+The recommended way of installing Sphinx is via `pip` using
+
+```bash
+pip install -U sphinx
+```
+
+Sphinx requires certain packages to build this documentation. These are summarized in `doc/requirements.txt`. They can automatically be installed using
+
+```bash
+cd doc
+pip install -r requirements.txt
+```
+
+## Building the documentation
+
+To build the documentation, switch to the `doc` folder if not already done. Build is invoked via the `make` command. Typically, an HTML should be build. 
+
+```bash
+cd doc
+make html
+```
+
+Simply type only `make` to view other available targets.

doc/_static/css/custom.css

@@ -0,0 +1,3 @@
+.no-scrollbar-table td {
+  white-space: normal !important;
+}

doc/conf.py

@@ -1,34 +1,53 @@
-# Copyright lowRISC contributors.
-# Licensed under the Apache License, Version 2.0, see LICENSE for details.
-# SPDX-License-Identifier: Apache-2.0
+# -*- coding: utf-8 -*-
 #
-# Sphinx configuration file for the Ibex documentation
+#  Copyright (c) 2020, 2023 OpenHW Group
 #
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+#  Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+# 
+#  https://solderpad.org/licenses/
+# 
+#  Unless required by applicable law or agreed to in writing, software
+#  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.
+# 
+#  SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0
+#
+###############################################################################
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os
-import sys
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
 
-# Source top directory
-topsrcdir = os.path.join(os.path.dirname(__file__), '..')
 
-old_sys_path = sys.path
-try:
-    sys.path.append(os.path.join(topsrcdir, 'util'))
-    import check_tool_requirements as ctr
-finally:
-    sys.path = old_sys_path
+# -- Project information -----------------------------------------------------
 
+project = 'CV32E20 Documentation'
+copyright = '2017-2018, ETH Zurich and University of Bologna, 2018-2022 lowRISC, 2022-2023 OpenHW Group'
+author = 'OpenHW Group'
+
+# The short X.Y version
+version = u'0.1'
+# The full version, including alpha/beta/rc tags
+release = u'0.1'
 
-numfig=True
-numfig_format = {'figure': 'Figure %s', 'table': 'Table %s', 'code-block': 'Listing %s'}
 
-# -- General configuration ------------------------------------------------
+# -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
@@ -38,6 +57,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx_github_changelog',
     'sphinxcontrib.wavedrom',
     'sphinx.ext.todo',
 ]
@@ -47,7 +68,7 @@
 render_using_wavedrompy = True
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ['ytemplates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -58,21 +79,6 @@
 # The master toctree document.
 master_doc = 'index'
 
-# General information about the project.
-project = 'Ibex Documentation'
-copyright = '2017-2018, ETH Zurich and University of Bologna, 2018-present lowRISC'
-author = 'lowRISC contributors'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = ''
-# The full version, including alpha/beta/rc tags.
-from setuptools_scm import get_version
-release = get_version(root=topsrcdir)
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -82,43 +88,60 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv']
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+# Numbering
+numfig=True
+numfig_format = {'figure': 'Figure %s', 'table': 'Table %s', 'code-block': 'Listing %s'}
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
 
 
-# -- Options for HTML output ----------------------------------------------
+# -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
+#html_theme = 'alabaster'
 html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-html_theme_options = {
-    'style_nav_header_background': '#E53651'
-}
-
-html_logo = 'images/logo.svg'
+html_theme_options = {'style_nav_header_background': '#DDDDDD'}
+html_logo = '../images/openhw-landscape.svg'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['ystatic']
+# Set html_static_path to null on the advice of RTDs:
 html_static_path = ['_static']
 
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
 html_css_files = [
-    'theme_overrides.css', # Fix wide tables in RTD theme
+  'css/custom.css',
 ]
 
-# -- Options for LaTeX output ---------------------------------------------
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'CORE-V_CV32E20_Documentation'
+
+
+# -- Options for LaTeX output ------------------------------------------------
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
@@ -142,39 +165,76 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ibex.tex', u'Ibex Documentation',
-     u'lowRISC', 'manual'),
+    (master_doc, 'CV32E20_Documentation.tex', u'CV32E20 Documentation',
+     u'OpenHW Group', 'manual'),
 ]
 
-latex_logo = ''
 
-# -- Options for manual page output ---------------------------------------
+# -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'ibex', u'Ibex Documentation',
+    (master_doc, 'CV32E20_Documentation.tex', u'CORE-V-Docs Documentation',
      [author], 1)
 ]
 
 
-# -- Options for Texinfo output -------------------------------------------
+# -- Options for Texinfo output ----------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'ibex', u'Ibex Documentation',
-     author, 'ibex', 'Ibex RV32 CPU core',
+    (master_doc, 'CV32E20_Documentation.tex', u'CORE-V-Docs Documentation',
+     author, 'Documentation', 'Documentation for CV32E20 CORE-V processor core.',
      'Miscellaneous'),
 ]
 
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------
+
+# -- Options for todo extension ----------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
 # -- Tool version numbers -------------------------------------------------
 
 # Add minimum versions of required tools as variables for use inside the
 # documentation.
+import os
+import sys
+
+# Source top directory
+topsrcdir = os.path.join(os.path.dirname(__file__), '..')
+
+old_sys_path = sys.path
+try:
+    sys.path.append(os.path.join(topsrcdir, 'util'))
+    import check_tool_requirements as ctr
+finally:
+    sys.path = old_sys_path
 tool_reqs = ctr.read_tool_requirements()
 rst_epilog = ""
 for tool, req in tool_reqs.items():
     rst_epilog += (".. |tool_requirements.{}| replace:: {}\n"
-                   .format(tool, req.min_version))
+                   .format(tool, req.min_version))