diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..cef07bf1c --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,26 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-20.04 + tools: + python: "3.9" + jobs: + pre_build: + - make apidoc + - breathe-apidoc -o docs/api apidoc/xml + +# Build documentation in the docs/ directory with Sphinx +sphinx: + builder: dirhtml + configuration: docs/conf.py + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt diff --git a/docs/.gitignore b/docs/.gitignore index 23f832b73..11f197bc3 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,4 @@ *.html *.pdf +_build/ +api/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..47510f984 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,40 @@ +# 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 clean apidoc breathe_apidoc Makefile + +# Intercept the 'clean' target so we can do the right thing for apidoc as well +clean: + @# Clean the apidoc + $(MAKE) -C .. apidoc_clean + @# Clean the breathe-apidoc generated files + rm -rf ./api + @# Clean the sphinx docs + @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +apidoc: + @# Generate doxygen from source using the main Makefile + $(MAKE) -C .. apidoc + +breathe_apidoc: apidoc + @# Remove existing files - breathe-apidoc skips them if they're present + rm -rf ./api + @# Generate RST file structure with breathe-apidoc + breathe-apidoc -o ./api ../apidoc/xml + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile breathe_apidoc + @# Build the relevant target with sphinx + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..41c50c7f2 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,34 @@ +# 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 +import glob + +project = 'Mbed TLS Versioned' +copyright = '2023, Mbed TLS Contributors' +author = 'Mbed TLS Contributors' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['breathe', 'sphinx.ext.graphviz'] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +breathe_projects = { + 'mbedtls-versioned': '../apidoc/xml' +} +breathe_default_project = 'mbedtls-versioned' + +primary_domain = 'c' +highlight_language = 'c' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..33a97223d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. Mbed TLS Versioned documentation master file, created by + sphinx-quickstart on Thu Feb 23 18:13:44 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Mbed TLS API documentation +========================== + +.. doxygenpage:: index + :project: mbedtls-versioned + +.. toctree:: + :caption: Contents + :maxdepth: 1 + + Home + api/grouplist.rst + api/filelist.rst + api/structlist.rst + api/unionlist.rst diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 000000000..a523188c3 --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,2 @@ +sphinx-rtd-theme +breathe diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..4b9f3a6b3 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,66 @@ +# +# This file is autogenerated by pip-compile with Python 3.9 +# by the following command: +# +# pip-compile requirements.in +# +alabaster==0.7.13 + # via sphinx +babel==2.12.1 + # via sphinx +breathe==4.35.0 + # via -r requirements.in +certifi==2022.12.7 + # via requests +charset-normalizer==3.1.0 + # via requests +docutils==0.17.1 + # via + # breathe + # sphinx + # sphinx-rtd-theme +idna==3.4 + # via requests +imagesize==1.4.1 + # via sphinx +importlib-metadata==6.0.0 + # via sphinx +jinja2==3.1.2 + # via sphinx +markupsafe==2.1.2 + # via jinja2 +packaging==23.0 + # via sphinx +pygments==2.14.0 + # via sphinx +requests==2.28.2 + # via sphinx +snowballstemmer==2.2.0 + # via sphinx +sphinx==4.5.0 + # via + # breathe + # sphinx-rtd-theme +sphinx-rtd-theme==1.2.0 + # via -r requirements.in +sphinxcontrib-applehelp==1.0.4 + # via sphinx +sphinxcontrib-devhelp==1.0.2 + # via sphinx +sphinxcontrib-htmlhelp==2.0.1 + # via sphinx +sphinxcontrib-jquery==2.0.0 + # via sphinx-rtd-theme +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==1.0.3 + # via sphinx +sphinxcontrib-serializinghtml==1.1.5 + # via sphinx +urllib3==1.26.15 + # via requests +zipp==3.15.0 + # via importlib-metadata + +# The following packages are considered to be unsafe in a requirements file: +# setuptools diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 5e797434d..393fd41ad 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -18,6 +18,7 @@ HTML_OUTPUT = . HTML_TIMESTAMP = YES SEARCHENGINE = YES GENERATE_LATEX = NO +GENERATE_XML = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES INCLUDE_PATH = ../include @@ -42,3 +43,12 @@ DOT_TRANSPARENT = YES # \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription # This avoids writing redundant text and keeps Clang happy. ALIASES += emptydescription="" + +# Define away Mbed TLS macros that make parsing definitions difficult. +# MBEDTLS_DEPRECATED is not included in this list as it's important to +# display deprecated status in the documentation. +PREDEFINED = "MBEDTLS_CHECK_RETURN_CRITICAL=" \ + "MBEDTLS_CHECK_RETURN_TYPICAL=" \ + "MBEDTLS_CHECK_RETURN_OPTIONAL=" \ + "MBEDTLS_PRINTF_ATTRIBUTE(a,b)=" \ + diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h index b1d4b88ba..5c2c8431b 100644 --- a/include/mbedtls/bignum.h +++ b/include/mbedtls/bignum.h @@ -1005,7 +1005,7 @@ int mbedtls_mpi_inv_mod(mbedtls_mpi *X, const mbedtls_mpi *A, * This must point to an initialized MPI. * \param rounds The number of bases to perform the Miller-Rabin primality * test for. The probability of returning 0 on a composite is - * at most 2-2*\p rounds. + * at most 2-2*\p rounds . * \param f_rng The RNG function to use. This must not be \c NULL. * \param p_rng The RNG parameter to be passed to \p f_rng. * This may be \c NULL if \p f_rng doesn't use