Merge pull request #5 from Infineon/docs/rtd-setup

Setup config files, folder structure & action for rtd docs

.github/workflows/docs.yml

@@ -0,0 +1,23 @@
+name: Build docs
+
+on:
+ push:
+ pull_request:
+ paths:
+ - docs/**
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ - name: Install Python packages
+ run: pip install -r docs/requirements.txt
+ - name: Build docs
+ run: make -C docs/ html

docs/Makefile

@@ -5,7 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS ?=
 SPHINXBUILD ?= sphinx-build
-SOURCEDIR = source
+SOURCEDIR = .
 BUILDDIR = build
 
 LINKCHECKDIR = build/linkcheck

docs/_templates/layout.html

@@ -0,0 +1,70 @@
+{% extends "!layout.html" %}
+ {% block footer %} {{ super() }}
+
+ <style>
+ /* Sidebar header (and topbar for mobile) */
+ .wy-side-nav-search, .wy-nav-top {
+ background: #0A8276;
+ }
+ /* Sidebar */
+ .wy-nav-side {
+ background: #0A8276;
+ }
+
+ /* span.caption-text {
+ color: white;
+ } */
+
+ .wy-menu-vertical header, .wy-menu-vertical p.caption {
+ color: white;
+ height: 32px;
+ display: inline-block;
+ line-height: 32px;
+ padding: 0 1.618em;
+ margin: 12px 0 0 0;
+ display: block;
+ font-weight: bold;
+ text-transform: uppercase;
+ font-size: 85%;
+ white-space: nowrap;
+ }
+
+ /*
+ .wy-side-nav-search>a, .wy-side-nav-search .wy-dropdown>a {
+ color: #3a7ca8;
+ font-size: 100%;
+ font-weight: bold;
+ display: inline-block;
+ padding: 4px 6px;
+ margin-bottom: .809em;
+ }
+ */
+
+ .wy-menu-vertical header, .wy-menu-vertical p.caption {
+ color: white;
+ height: 32px;
+ display: inline-block;
+ line-height: 32px;
+ padding: 0 1.618em;
+ margin: 12px 0 0 0;
+ display: block;
+ font-weight: bold;
+ text-transform: uppercase;
+ font-size: 85%;
+ white-space: nowrap;
+ }
+
+ .rst-versions {
+ position: fixed;
+ bottom: 0;
+ left: 0;
+ width: 300px;
+ color: #fcfcfc;
+ background: #6CB4AD;
+ font-family: "Lato","proxima-nova", "Helvetica Neue", Arial,sans-serif;
+ z-index: 400;
+ justify-content: stretch;
+ }
+
+ </style>
+{% endblock %}

docs/conf.py

@@ -0,0 +1,116 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains 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.
+#
+
+from recommonmark.parser import CommonMarkParser
+from sphinx.builders.html import StandaloneHTMLBuilder
+import subprocess, os, sys
+import textwrap
+
+# Check if we're running on Read the Docs' servers
+read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+
+# -- Project information -----------------------------------------------------
+
+project = 'Arduino Core for PSoC™'
+copyright = '2024 Infineon Technologies AG'
+author = 'Infineon Technologies AG'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+#...
+
+# At top on conf.py (with other import statements)
+# import recommonmark
+# from recommonmark.transform import AutoStructify
+
+# # At the bottom of conf.py
+# def setup(app):
+# app.add_config_value('recommonmark_config', {
+# 'url_resolver': lambda url: github_doc_root + url,
+# 'auto_toc_tree_section': 'Contents',
+# }, True)
+# app.add_transform(AutoStructify)
+
+extensions = [
+ # 'sphinx.ext.autodoc',
+ # 'sphinxemoji.sphinxemoji',
+ # 'sphinx_tabs.tabs',
+ # 'sphinx.ext.intersphinx',
+ # 'sphinx.ext.autosectionlabel',
+ # 'sphinx.ext.todo',
+ # 'sphinx.ext.coverage',
+ # 'sphinx.ext.mathjax',
+ # 'sphinx.ext.ifconfig',
+ # 'sphinx.ext.viewcode',
+ # 'sphinx_sitemap',
+ # 'sphinx.ext.graphviz',
+ # 'sphinx.ext.inheritance_diagram',
+ # 'breathe',
+ # 'exhale'
+
+]
+
+autosectionlabel_prefix_document = True
+# source_parsers = {
+# '.md': 'recommonmark.parser.CommonMarkParser',
+# }
+
+source_suffix = [
+ '.rst',
+ # '.md'
+]
+
+suppress_warnings = ['autosectionlabel.*', 'epub.duplicated_toc_entry']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# Tell sphinx what the primary language being documented is.
+primary_domain = 'cpp'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'build', 'Thumbs.db', '.DS_Store']
+
+highlight_language = 'c++'
+
+# -- 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 = 'sphinx_rtd_theme'
+# html_theme_options = {
+# "head_font_family" : "Source Sans Pro",
+# "font_family" : "Source Sans Pro",
+# "body_text_align" : "justify",
+# }
+
+html_logo = 'img/ifx_logo_white_green_s.png'
+
+# 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 = ['_templates']
+
+# -- Breathe configuration -------------------------------------------------
+
+breathe_projects = {
+ "Arduino Core for PSoC": "build/xml/"
+}
+breathe_default_project = "Arduino Core for PSoC"
+breathe_default_members = ('members', 'undoc-members')

docs/hw-platforms.rst

@@ -0,0 +1,17 @@
+Supported Boards
+=================
+
+CY8CKIT-062S2-AI
+----------------
+
+.. image:: img/board_CY8CKIT-062S2-AI.png
+ :width: 300
+
+`CY8CKIT-062S2-AI`_
+
+Pinout Diagram
+^^^^^^^^^^^^^^
+
+...
+
+.. _`CY8CKIT-062S2-AI`: https://www.infineon.com/cms/en/product/evaluation-boards/cy8ckit-062s2-ai/

docs/index.rst

@@ -0,0 +1,20 @@
+**********************
+Arduino Core for PSoC™
+**********************
+Welcome to the Arduino Core for Infineon's PSoC™ microcontrollers.
+
+.. image:: img/board_CY8CKIT-062S2-AI.png
+ :width: 200
+
+.. toctree::
+ :maxdepth: 2
+ :caption: CONTENT:
+
+ Introduction<self>
+ installation-instructions
+ hw-platforms
+
+License
+=======
+
+Please find the license file for this core `here <https://github.com/Infineon/arduino-core-psoc/blob/master/LICENSE.md>`_.

docs/installation-instructions.rst

@@ -0,0 +1,33 @@
+Installation Instructions
+===========================
+
+Required Tools
+--------------
+...
+
+Integration in Arduino IDE
+--------------------------
+.. note::
+ We recommended to use Arduino IDE 2.0 or higher.
+
+.. image:: img/install_preferences_menu.png
+ :width: 600
+
+Paste the following URL into the *Additional boards manager URLs* input field under *File > Preferences* to add Infineon's PSoC™ microcontroller boards to the Arduino IDE.
+
+.. code-block::
+ https://github.com/Infineon/arduino-core-psoc/releases/latest/download/package_infineon_index.json
+
+.. image:: img/install_preferences_json.png
+ :width: 600
+
+To install the boards, navigate to *Tools > Board > Boards Manager...* and search for *PSoC*. You will see options to install the board files for the microcontrollers. 
+Click *Install* to add the boards to your Arduino IDE.
+
+.. image:: img/install_board_manager_entry.png
+ :width: 600
+
+In the boards list *Tools > Board*, you will now find the supported PSoC™ microcontroller boards.
+
+.. image:: img/install_board_list.png
+ :width: 600

docs/make.bat

@@ -7,7 +7,7 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
  set SPHINXBUILD=sphinx-build
 )
-set SOURCEDIR=source
+set SOURCEDIR=.
 set BUILDDIR=build
 
 if "%1" == "" goto help

docs/requirements.txt

@@ -1,6 +1,8 @@
 # This is a list of python packages used to generate documentation. This file is used with pip:
 # pip install --user -r requirements.txt
 #
-# matplotlib is currently required only by the script generate_chart.py
-sphinx-copybutton==0.3.0
-sphinx-tabs==3.2.0
+sphinx>=7.2.6
+sphinx-tabs
+sphinxemoji
+sphinx-rtd-theme
+recommonmark>=0.6.0