Feat: support ci profile

.github/workflows/test-python.yml

@@ -39,7 +39,7 @@ jobs:
           pip install -e '.[test]'
       - name: Run tests with pytest and coverage
         run: |
-          pytest --junitxml pytest.xml --cov-report term-missing:skip-covered --cov idf_ci tests/ | tee pytest-coverage.txt
+          pytest --junitxml pytest.xml --cov-report term-missing --cov idf_ci tests/ | tee pytest-coverage.txt
       - name: Upload coverage report to PR (Python 3.13 only)
         if: matrix.python-version == '3.13' && github.event_name == 'pull_request'
         uses: MishaKav/pytest-coverage-comment@v1

.gitignore

@@ -73,7 +73,8 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/*/_build/
+docs/*/references/api/
 
 # PyBuilder
 .pybuilder/

.pre-commit-config.yaml

@@ -1,13 +1,13 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: 'v5.0.0'
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: mixed-line-ending
         args: [ '-f=lf' ]
   - repo: https://github.com/Lucas-C/pre-commit-hooks
-    rev: v1.5.5
+    rev: 'v1.5.5'
     hooks:
       - id: insert-license
         files: \.py$
@@ -16,7 +16,7 @@ repos:
           - license_header.txt        # defaults to: LICENSE.txt
           - --use-current-year
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: 'v0.8.4'
+    rev: 'v0.9.1'
     hooks:
       - id: ruff
         args: ['--fix']
@@ -33,3 +33,13 @@ repos:
           - tomlkit
           - idf-build-apps~=2.6
           - pytest-embedded~=1.12
+  - repo: https://github.com/hfudev/rstfmt
+    rev: 'v0.1.4'
+    hooks:
+      - id: rstfmt
+        args: ['-w', '-1']
+        files: "docs\/.+rst$"
+        additional_dependencies:
+          - sphinx-argparse
+          - sphinx-tabs
+          - sphinxcontrib-mermaid

docs/_apidoc_templates/module.rst_t

@@ -0,0 +1,8 @@
+{%- if show_headings %}
+{{- [basename, "module"] | join(' ') | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}

docs/_apidoc_templates/package.rst_t

@@ -0,0 +1,49 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname, "namespace"] | join(" ") | e | heading }}
+{% else %}
+{{- [pkgname, "package"] | join(" ") | e | heading }}
+{% endif %}
+
+{%- if is_namespace %}
+.. py:module:: {{ pkgname }}
+{% endif %}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if subpackages %}
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}
+
+{%- if not modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}

docs/_apidoc_templates/toc.rst_t

@@ -0,0 +1,7 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}

docs/_static/theme_overrides.css

@@ -0,0 +1,55 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+    .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+    }
+
+    .wy-table-responsive {
+      overflow: visible !important;
+    }
+  }
+
+  .wy-side-nav-search {
+    background-color: #e3e3e3 !important;
+  }
+
+  .wy-side-nav-search input[type=text] {
+     border-radius: 0px !important;
+     border-color: #333333 !important;
+  }
+
+  .icon-home {
+    color: #333333 !important;
+  }
+
+  .icon-home:hover {
+    background-color: #d6d6d6 !important;
+  }
+
+  .version {
+    color: #000000 !important;
+  }
+
+  a:hover {
+    color: #bd2c2a !important;
+  }
+
+  .logo {
+    width: 240px !important;
+  }
+
+  .highlight .c1 {
+      color: #008080;
+  }
+
+  .bolditalics {
+      font-weight: bold;
+      font-style: italic;
+  }
+
+pre {
+    white-space: pre-wrap !important;
+}

docs/_templates/layout.html

@@ -0,0 +1,7 @@
+{% extends "!layout.html" %}
+
+{% block document %}
+<!--email_off-->
+    {{ super() }}
+<!--/email_off-->
+{% endblock %}

docs/conf_common.py

@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import subprocess
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'idf-ci'
+project_homepage = 'https://github.com/espressif/idf-ci'
+copyright = '2025, Espressif Systems (Shanghai) Co., Ltd.'  # noqa: A001
+author = 'Fu Hanxi'
+languages = ['en']
+version = '0.x'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx_copybutton',
+    'myst_parser',
+    'sphinxcontrib.mermaid',
+    'sphinxarg.ext',
+    'sphinx_tabs.tabs',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_css_files = ['theme_overrides.css']
+html_logo = '../_static/espressif-logo.svg'
+html_static_path = ['../_static']
+html_theme = 'sphinx_rtd_theme'
+
+
+def generate_api_docs(language):
+    subprocess.run(
+        [
+            'sphinx-apidoc',
+            os.path.join(os.path.dirname(__file__), '..', 'idf_ci'),
+            '--remove-old',
+            '-f',
+            '-H',
+            'API Reference',
+            '--no-headings',
+            '-t',
+            '_apidoc_templates',
+            '-o',
+            os.path.join(os.path.dirname(__file__), language, 'references', 'api'),
+        ]
+    )

docs/en/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     = .
+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/en/conf.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import sys
+
+language = 'en'
+
+sys.path.insert(0, os.path.abspath('../'))
+
+from conf_common import *  # noqa
+
+generate_api_docs(language)  # noqa