diff --git a/.gitignore b/.gitignore index fddebbd..e76aece 100644 --- a/.gitignore +++ b/.gitignore @@ -8,5 +8,7 @@ dist **__pycache__ .eggs/ .tox -.coverage +*coverage* *.pyc +.doc/** + diff --git a/REUSE.toml b/REUSE.toml new file mode 100644 index 0000000..b027425 --- /dev/null +++ b/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 " +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" diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..3c98659 --- /dev/null +++ b/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)", +} diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..7ca0428 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,12 @@ +.. _svd2json: + +.. highlight:: python + +Welcome to svd2json documentation! +********************************** + +.. toctree:: + :maxdepth: 3 + :caption: Contents: + + python_api.rst diff --git a/doc/python_api.rst b/doc/python_api.rst new file mode 100644 index 0000000..b5a3d2d --- /dev/null +++ b/doc/python_api.rst @@ -0,0 +1,8 @@ +svd2json Python API +=================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + autoapi/svd2json/index diff --git a/pyproject.toml b/pyproject.toml index fea2b53..87fb41e 100644 --- a/pyproject.toml +++ b/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", diff --git a/tox.ini b/tox.ini index ed3d257..b250f25 100644 --- a/tox.ini +++ b/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