Skip to content

Commit c4bb23a

Browse files
jaenrig-ifxjaenrig-ifx
committed
docs: Added readthedocs struct, docs structure and overview section.
Signed-off-by: jaenrig-ifx <enriquezgarcia.external@infineon.com>
1 parent 3a61b89 commit c4bb23a

File tree

14 files changed

+429
-0
lines changed

14 files changed

+429
-0
lines changed

‎docs/Makefile

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = build
10+
11+
LINKCHECKDIR = build/linkcheck
12+
13+
.PHONY: checklinks
14+
checklinks:
15+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(LINKCHECKDIR)
16+
@echo
17+
@echo "Check finished. Report is in $(LINKCHECKDIR)."
18+
19+
# Put it first so that "make" without argument is like "make help".
20+
help:
21+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
22+
23+
.PHONY: help Makefile
24+
25+
# Catch-all target: route all unknown targets to Sphinx using the new
26+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
27+
%: Makefile
28+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/_templates/layout.html

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
{% extends "!layout.html" %}
2+
{% block footer %} {{ super() }}
3+
4+
<style>
5+
/* Sidebar header (and topbar for mobile) */
6+
.wy-side-nav-search, .wy-nav-top {
7+
background: #0A8276;
8+
}
9+
/* Sidebar */
10+
.wy-nav-side {
11+
background: #0A8276;
12+
}
13+
14+
/* span.caption-text {
15+
color: white;
16+
} */
17+
18+
.wy-menu-vertical header, .wy-menu-vertical p.caption {
19+
color: white;
20+
height: 32px;
21+
display: inline-block;
22+
line-height: 32px;
23+
padding: 0 1.618em;
24+
margin: 12px 0 0 0;
25+
display: block;
26+
font-weight: bold;
27+
text-transform: uppercase;
28+
font-size: 85%;
29+
white-space: nowrap;
30+
}
31+
32+
/*
33+
.wy-side-nav-search>a, .wy-side-nav-search .wy-dropdown>a {
34+
color: #3a7ca8;
35+
font-size: 100%;
36+
font-weight: bold;
37+
display: inline-block;
38+
padding: 4px 6px;
39+
margin-bottom: .809em;
40+
}
41+
*/
42+
43+
.wy-menu-vertical header, .wy-menu-vertical p.caption {
44+
color: white;
45+
height: 32px;
46+
display: inline-block;
47+
line-height: 32px;
48+
padding: 0 1.618em;
49+
margin: 12px 0 0 0;
50+
display: block;
51+
font-weight: bold;
52+
text-transform: uppercase;
53+
font-size: 85%;
54+
white-space: nowrap;
55+
}
56+
57+
.rst-versions {
58+
position: fixed;
59+
bottom: 0;
60+
left: 0;
61+
width: 300px;
62+
color: #fcfcfc;
63+
background: #6CB4AD;
64+
font-family: "Lato","proxima-nova", "Helvetica Neue", Arial,sans-serif;
65+
z-index: 400;
66+
justify-content: stretch;
67+
}
68+
69+
</style>
70+
{% endblock %}

‎docs/compile-examples/index.rst

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Compile examples
2+
================
3+
4+
Description
5+
------------
6+
7+
.. _compile_examples_getting_started:
8+
9+
Getting started
10+
----------------
11+
12+
Usage
13+
-----
14+
15+
The compile matrix
16+
------------------
17+
18+
Dependency installation
19+
-----------------------
20+

‎docs/conf.py

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# http://www.sphinx-doc.org/en/master/config
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
14+
from recommonmark.parser import CommonMarkParser
15+
from sphinx.builders.html import StandaloneHTMLBuilder
16+
import subprocess, os, sys
17+
import textwrap
18+
19+
# Check if we're running on Read the Docs' servers
20+
read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True"
21+
22+
# -- Project information -----------------------------------------------------
23+
24+
project = "Arduino DevOps"
25+
copyright = "2025 Infineon Technologies AG"
26+
author = "Infineon Technologies AG"
27+
28+
# -- General configuration ---------------------------------------------------
29+
30+
# Add any Sphinx extension module names here, as strings. They can be
31+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32+
# ones.
33+
# ...
34+
35+
# At top on conf.py (with other import statements)
36+
# import recommonmark
37+
# from recommonmark.transform import AutoStructify
38+
39+
# # At the bottom of conf.py
40+
# def setup(app):
41+
# app.add_config_value('recommonmark_config', {
42+
# 'url_resolver': lambda url: github_doc_root + url,
43+
# 'auto_toc_tree_section': 'Contents',
44+
# }, True)
45+
# app.add_transform(AutoStructify)
46+
47+
extensions = [
48+
"sphinx_tabs.tabs",
49+
"sphinxemoji.sphinxemoji",
50+
"myst_parser",
51+
]
52+
53+
autosectionlabel_prefix_document = True
54+
55+
source_suffix = [
56+
".rst",
57+
]
58+
59+
suppress_warnings = ["autosectionlabel.*", "epub.duplicated_toc_entry"]
60+
61+
# Add any paths that contain templates here, relative to this directory.
62+
templates_path = ["_templates"]
63+
64+
# Tell sphinx what the primary language being documented is.
65+
primary_domain = "cpp"
66+
67+
# List of patterns, relative to source directory, that match files and
68+
# directories to ignore when looking for source files.
69+
# This pattern also affects html_static_path and html_extra_path.
70+
exclude_patterns = ["_build", "build", "Thumbs.db", ".DS_Store"]
71+
72+
highlight_language = "c++"
73+
74+
# -- Options for HTML output -------------------------------------------------
75+
76+
# The theme to use for HTML and HTML Help pages. See the documentation for
77+
# a list of builtin themes.
78+
79+
html_theme = "sphinx_rtd_theme"
80+
81+
html_logo = "img/ifx_logo_white_green_s.png"
82+
83+
# Add any paths that contain custom static files (such as style sheets) here,
84+
# relative to this directory. They are copied after the builtin static files,
85+
# so a file named "default.css" will overwrite the builtin "default.css".
86+
html_static_path = ["_templates"]
87+

‎docs/img/arduino-logo.png

3.31 KB
Loading

‎docs/img/ifx_logo_white_green_s.png

2.69 KB
Loading

‎docs/index.rst

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
*******************
2+
Arduino DevOps Docs
3+
*******************
4+
5+
Welcome to the **Arduino DevOps Docs**!👋
6+
7+
We hope you find in these pages **all the required information** to use Arduino DevOps utilities. If that is not the case, let us know in the `issue <https://github.com/Infineon/arduino-devops/issues>`_ section.
8+
9+
.. warning::
10+
11+
This repository is a work in progress. Changes not compatible with the current version may be introduced in the future.
12+
13+
.. toctree::
14+
:maxdepth: 1
15+
:caption: Overview
16+
17+
overview/motivation
18+
overview/content
19+
overview/usage
20+
overview/requirements
21+
22+
.. toctree::
23+
:maxdepth: 3
24+
:caption: Workflows
25+
26+
compile-examples/index
27+
release/index
28+
29+
.. toctree::
30+
:maxdepth: 2
31+
:caption: Scripts
32+
33+
scripts/scripts

‎docs/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/overview/content.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Content
2+
========
3+
4+
The repository contains the following directories and files:
5+
6+
- `.github/workflows <https://github.com/Infineon/arduino-devops/tree/main/.github/workflows>`_. Reusable workflows for for Arduino assets DevOps processes. Additionally, it can contains workflows used by the repository itself.
7+
- `config <https://github.com/Infineon/arduino-devops/tree/main/config>`_. Default configuration files for the reusable workflows. It can be used as a template to create the configuration files for your own repository.
8+
- `docs <https://github.com/Infineon/arduino-devops/tree/main/docs>`_. Docs sources for these pages.
9+
- `tests <https://github.com/Infineon/arduino-devops/tree/main/tests>`_. Some basic tests used during the development of some of the scripts. Most of the scripts do not have any tests.
10+
- `/(root) <https://github.com/Infineon/arduino-devops/tree/main>`_. Python scripts that implement the DevOps utilities. Additionally, it contains other metafiles. These should (soon) become a python package that can be installed via pip.

‎docs/overview/motivation.rst

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Introduction
2+
============
3+
4+
Motivation
5+
----------
6+
7+
This project was initiated to address the need for harmonizing and effectively managing DevOps processes for multiple Arduino libraries and cores developed and maintained by Infineon Technologies AG. The primary goal is to streamline and automate tasks, ensuring seamless integration and efficient management of Arduino assets.
8+
9+
Background
10+
----------
11+
12+
The introduction of `arduino-cli <https://docs.arduino.cc/arduino-cli/>`_ has been a significant step forward in enabling programmatic handling of the Arduino toolchain and processes. This has opened up possibilities for automation via scripts and command line interfaces, making it easier to integrate tasks like build verification and testing into continuous integration servers.
13+
14+
Current State and Objectives
15+
----------------------------
16+
17+
While existing DevOps solutions, such as `compile-sketches action <https://github.com/arduino/compile-sketches>`_, provide some functionality, they do not fully meet our requirements. This project aims to fill this gap by providing a collection of utilities that solve specific DevOps use cases for managing Arduino assets. The scope of this project is intentionally open-ended, allowing it to evolve and adapt to emerging needs.
18+
19+
Key Features and Design Principles
20+
----------------------------------
21+
22+
The project's features are designed to be used via command line interface, making it easy to integrate with any non-GUI CI/CD framework and environment. Python is the language of choice, ensuring cross-platform compatibility. Although our primary development and testing platform is Linux, we strive to ensure platform independence.
23+
24+
When applicable, the features presented rely on the Arduino `platform <https://docs.arduino.cc/arduino-cli/platform-specification>`_ and `library <https://docs.arduino.cc/arduino-cli/library-specification/>`_ specifications.
25+
26+
The solutions provided for CI/CD are implemented through GitHub Actions `reusable workflows <https://docs.github.com/en/actions/sharing-automations/reusing-workflows>`_. This allows for easy deployment and upgrading of workflows with minimal effort. Given GitHub's popularity among Arduino developers, we have chosen to focus on GitHub Actions initially. However, we believe it should be straightforward to port the workflows to other CI/CD frameworks, such as GitLab, Jenkins, or Travis.
27+
28+
Community Engagement and Contributions
29+
--------------------------------------
30+
31+
We believe these tools can be of general interest and applicability to any Arduino library or core developer. We encourage users to try them out, provide feedback, and contribute to making them more extensible and adaptable to various use cases.

0 commit comments

Comments
 (0)