Merge pull request #12 from fvalette-ledger/add-api-doc

Add api doc

.gitignore

@@ -8,5 +8,7 @@ dist
 **__pycache__
 .eggs/
 .tox
-.coverage
+*coverage*
 *.pyc
+.doc/**
+

REUSE.toml

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2024 Ledger SAS
+#
+# SPDX-License-Identifier: Apache-2.0
+
+version = 1
+SPDX-PackageName = "svd2json"
+SPDX-PackageSupplier = "Ledger SAS <[email protected]>"
+SPDX-PackageDownloadLocation = "https://github.com/outpost-os/python-svd2json"
+
+[[annotations]]
+path = "doc/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2024 Ledger SAS"
+SPDX-License-Identifier = "Apache-2.0"

doc/conf.py

@@ -0,0 +1,77 @@
+from importlib import metadata
+
+# General information about the project.
+project = "svd2json"
+copyright = "2024, Ledger SAS"
+author = "Ledger"
+
+# XXX:
+# Project base on PEP440 and setuptools_scm dynamic versioning
+# see: "Usage with Sphinx section" in https://setuptools-scm.readthedocs.io/en/stable/usage/
+release: str = metadata.version(project)
+version: str = ".".join(release.split(".")[:3])
+
+root_doc = "index"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+source_suffix = ".rst"
+source_encoding = "utf-8-sig"
+
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinx_simplepdf",
+    "sphinx.ext.todo",
+    "sphinx.ext.napoleon",
+    "autoapi.extension",
+]
+
+# Napoleon extension configuration
+napoleon_numpy_docstring = True
+napoleon_include_private_with_doc = True
+napoleon_attr_annotations = True
+
+# Autoapi configuration
+autoapi_dirs = ["../src"]
+autoapi_add_toctree_entry = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+# -- Options for HTML output ----------------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+
+# Any idea for non outpost specific python package ?
+# html_logo = '_static/figures/sentry_kernel.png'
+
+html_static_path = ["_static"]
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#
+html_use_smartypants = True
+
+html_show_sourcelink = False
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#
+html_show_sphinx = False
+
+htmlhelp_basename = "svd2json"
+
+simplepdf_vars = {
+    "primary": "#6299C4",
+    "primary-opaque": "#6299C4",
+    "secondary": "#6299C4",
+    "cover": "#ffffff",
+    "white": "#ffffff",
+    "links": "#6299C4",
+    "cover-overlay": "rgba(62, 99, 196, 0.5)",
+    "top-left-content": "counter(page)",
+}

doc/index.rst

@@ -0,0 +1,12 @@
+.. _svd2json:
+
+.. highlight:: python
+
+Welcome to svd2json documentation!
+**********************************
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   python_api.rst

doc/python_api.rst

@@ -0,0 +1,8 @@
+svd2json Python API
+===================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   autoapi/svd2json/index

pyproject.toml

@@ -55,7 +55,7 @@ doc = [
     "Sphinx>=7.2.0",
     "sphinx-rtd-theme>=2.0.0",
     "sphinx-simplepdf>=1.6.0",
-    # "sphinx-autoapi",
+    "sphinx-autoapi",
 ]
 license = [
     "reuse>=3.0.0",

tox.ini

@@ -9,7 +9,7 @@ env_list =
   type
   unittests
   htmlcov
-  # docs
+  docs
 isolated_build = true
 
 [tox:.package]
@@ -48,6 +48,10 @@ extras = license
 commands = reuse lint
 
 [testenv:docs]
+extras = doc
+commands =
+  sphinx-build -b singlehtml doc/ .doc/_html
+  sphinx-build -b simplepdf  doc/ .doc/_pdf
 
 [flake8]
 select = C, E, F, W, B, B9