From df28b8d2ea5bcd3e947b7f72bf6a21f25c06a2a7 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Thu, 23 Feb 2023 18:39:16 +0000 Subject: [PATCH 01/13] Add space to appease doxygen bug See doxygen/doxygen#8706 Signed-off-by: David Horstmann --- include/mbedtls/bignum.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h index b1d4b88ba5..5c2c8431b0 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 From 1d46bfbae8f1a8f6cf5dff1818e98259a4458523 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Tue, 14 Mar 2023 14:20:38 +0000 Subject: [PATCH 02/13] Tell Doxygen to generate XML Signed-off-by: David Horstmann --- doxygen/mbedtls.doxyfile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 5e797434db..1a421efd1f 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -42,3 +42,5 @@ DOT_TRANSPARENT = YES # \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription # This avoids writing redundant text and keeps Clang happy. ALIASES += emptydescription="" + +GENERATE_XML = YES From 7cedefe2fbd4d68d0e17cf643e23fcd6d75a6a78 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Tue, 14 Mar 2023 15:00:46 +0000 Subject: [PATCH 03/13] Add initial API doc configuration Signed-off-by: David Horstmann --- docs/Makefile | 20 +++++++++++ docs/conf.py | 34 ++++++++++++++++++ docs/index.rst | 20 +++++++++++ docs/make.bat | 35 ++++++++++++++++++ docs/requirements.in | 3 ++ docs/requirements.txt | 82 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 194 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/requirements.in create mode 100644 docs/requirements.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..d4bb2cbb9e --- /dev/null +++ b/docs/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) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..41c50c7f25 --- /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 0000000000..33a97223d2 --- /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/make.bat b/docs/make.bat new file mode 100644 index 0000000000..32bb24529f --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 0000000000..c0afd61586 --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,3 @@ +sphinx-rtd-theme +breathe +exhale diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000000..9d57fadde8 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,82 @@ +# +# This file is autogenerated by pip-compile with Python 3.8 +# by the following command: +# +# pip-compile requirements.in +# +alabaster==0.7.13 + # via sphinx +babel==2.12.1 + # via sphinx +beautifulsoup4==4.11.2 + # via exhale +breathe==4.35.0 + # via + # -r requirements.in + # exhale +certifi==2022.12.7 + # via requests +charset-normalizer==3.1.0 + # via requests +docutils==0.17.1 + # via + # breathe + # exhale + # sphinx + # sphinx-rtd-theme +exhale==0.3.6 + # via -r requirements.in +idna==3.4 + # via requests +imagesize==1.4.1 + # via sphinx +importlib-metadata==6.0.0 + # via sphinx +jinja2==3.1.2 + # via sphinx +lxml==4.9.2 + # via exhale +markupsafe==2.1.2 + # via jinja2 +packaging==23.0 + # via sphinx +pygments==2.14.0 + # via sphinx +pytz==2022.7.1 + # via babel +requests==2.28.2 + # via sphinx +six==1.16.0 + # via exhale +snowballstemmer==2.2.0 + # via sphinx +soupsieve==2.4 + # via beautifulsoup4 +sphinx==4.5.0 + # via + # breathe + # exhale + # 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 From bd2947684cb6adbbd22b773d1512fc6c5ac2208f Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Tue, 14 Mar 2023 16:38:36 +0000 Subject: [PATCH 04/13] Add configuration for Read The Docs Signed-off-by: David Horstmann --- .readthedocs.yaml | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..cef07bf1cc --- /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 From b9f0674ef194ea281b264c32fc663c82bf392e0d Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Thu, 16 Mar 2023 16:07:12 +0000 Subject: [PATCH 05/13] Ignore mbedtls macros causing warnings Sphinx's breathe plugin cannot readily parse the Mbed TLS macros, so define the less essential ones away at the doxygen step to reduce the number of warnings. Signed-off-by: David Horstmann --- doxygen/mbedtls.doxyfile | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 1a421efd1f..cd3937fdf3 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -44,3 +44,12 @@ DOT_TRANSPARENT = YES ALIASES += emptydescription="" GENERATE_XML = YES + +# 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)=" \ + From 1fa678d58e84b14cacb564c6abb1f8f699b9cd82 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Fri, 17 Mar 2023 13:46:51 +0000 Subject: [PATCH 06/13] Add exemption for make.bat in checks for tabs Signed-off-by: David Horstmann --- tests/scripts/check_files.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tests/scripts/check_files.py b/tests/scripts/check_files.py index 352b55eaa8..7cb3e0b41a 100755 --- a/tests/scripts/check_files.py +++ b/tests/scripts/check_files.py @@ -350,6 +350,7 @@ class TabIssueTracker(LineIssueTracker): ".sln", "/Makefile", "/Makefile.inc", + "/make.bat", "/generate_visualc_files.pl", ]) From 5532597de3ef7549b50ab3adbffce82f3f816c11 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Wed, 22 Mar 2023 17:30:22 +0000 Subject: [PATCH 07/13] Remove Exhale from requirements and regenerate Regenerate the requirements.txt with Exhale removed and also with Python 3.9 instead of 3.8, for parity with Read The Docs. Signed-off-by: David Horstmann --- docs/requirements.in | 1 - docs/requirements.txt | 20 ++------------------ 2 files changed, 2 insertions(+), 19 deletions(-) diff --git a/docs/requirements.in b/docs/requirements.in index c0afd61586..a523188c38 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -1,3 +1,2 @@ sphinx-rtd-theme breathe -exhale diff --git a/docs/requirements.txt b/docs/requirements.txt index 9d57fadde8..4b9f3a6b3f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.8 +# This file is autogenerated by pip-compile with Python 3.9 # by the following command: # # pip-compile requirements.in @@ -8,12 +8,8 @@ alabaster==0.7.13 # via sphinx babel==2.12.1 # via sphinx -beautifulsoup4==4.11.2 - # via exhale breathe==4.35.0 - # via - # -r requirements.in - # exhale + # via -r requirements.in certifi==2022.12.7 # via requests charset-normalizer==3.1.0 @@ -21,11 +17,8 @@ charset-normalizer==3.1.0 docutils==0.17.1 # via # breathe - # exhale # sphinx # sphinx-rtd-theme -exhale==0.3.6 - # via -r requirements.in idna==3.4 # via requests imagesize==1.4.1 @@ -34,28 +27,19 @@ importlib-metadata==6.0.0 # via sphinx jinja2==3.1.2 # via sphinx -lxml==4.9.2 - # via exhale markupsafe==2.1.2 # via jinja2 packaging==23.0 # via sphinx pygments==2.14.0 # via sphinx -pytz==2022.7.1 - # via babel requests==2.28.2 # via sphinx -six==1.16.0 - # via exhale snowballstemmer==2.2.0 # via sphinx -soupsieve==2.4 - # via beautifulsoup4 sphinx==4.5.0 # via # breathe - # exhale # sphinx-rtd-theme sphinx-rtd-theme==1.2.0 # via -r requirements.in From dbee883c74a6c1f43d7c2a9bc1a42f9708062571 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Wed, 22 Mar 2023 17:35:14 +0000 Subject: [PATCH 08/13] Improve positioning of GENERATE_XML option It is clearer to have this option next to the GENERATE_LATEX option. Signed-off-by: David Horstmann --- doxygen/mbedtls.doxyfile | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index cd3937fdf3..393fd41ad2 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 @@ -43,8 +44,6 @@ DOT_TRANSPARENT = YES # This avoids writing redundant text and keeps Clang happy. ALIASES += emptydescription="" -GENERATE_XML = YES - # 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. From e51ef92efd95e6bb0a6e792fce00cac67c0d0cfb Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Mon, 27 Mar 2023 15:21:27 +0100 Subject: [PATCH 09/13] Improve docs Makefile to do full build Include the make apidoc and breathe-apidoc steps in the documentation Makefile for ease of use. In this way, depart from the Makefile generated automatically by Sphinx. Signed-off-by: David Horstmann --- docs/Makefile | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index d4bb2cbb9e..6a7599e96e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,9 +12,27 @@ BUILDDIR = _build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.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 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 +%: Makefile breathe_apidoc + @# Build the relevant target with sphinx @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) From 8d7b213ef8c362597c1af13e5eba9c07a4a933d5 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Mon, 27 Mar 2023 15:24:37 +0100 Subject: [PATCH 10/13] Remove make.bat for documentation Building the docs on Windows is not supported in any case, as the apidoc target in the main Makefile will not run on Windows. Signed-off-by: David Horstmann --- docs/make.bat | 35 ----------------------------------- 1 file changed, 35 deletions(-) delete mode 100644 docs/make.bat diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 32bb24529f..0000000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd From 6c7785225280a2d5d78db34dc4357ffbbe1fad25 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Mon, 27 Mar 2023 15:30:40 +0100 Subject: [PATCH 11/13] Revert "Add exemption for make.bat in checks for tabs" This is no longer needed as make.bat has been removed. We do not support building the documentation on Windows. This reverts commit d50daedccace24bf69903ff7879bc0543757f5ef. Signed-off-by: David Horstmann --- tests/scripts/check_files.py | 1 - 1 file changed, 1 deletion(-) diff --git a/tests/scripts/check_files.py b/tests/scripts/check_files.py index 7cb3e0b41a..352b55eaa8 100755 --- a/tests/scripts/check_files.py +++ b/tests/scripts/check_files.py @@ -350,7 +350,6 @@ class TabIssueTracker(LineIssueTracker): ".sln", "/Makefile", "/Makefile.inc", - "/make.bat", "/generate_visualc_files.pl", ]) From 9d06c7d5e5c8ac08b2827021780cad7e39796632 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Tue, 28 Mar 2023 14:24:47 +0100 Subject: [PATCH 12/13] Clean the breathe-apidoc files with make clean Signed-off-by: David Horstmann --- docs/Makefile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/Makefile b/docs/Makefile index 6a7599e96e..47510f984d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -18,6 +18,8 @@ help: 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) From b7583c9a8fb0ef2ab8d7adc488209c189a385ed2 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Tue, 28 Mar 2023 15:00:24 +0100 Subject: [PATCH 13/13] Add _build/ and api/ to gitignore Signed-off-by: David Horstmann --- docs/.gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/.gitignore b/docs/.gitignore index 23f832b734..11f197bc35 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,4 @@ *.html *.pdf +_build/ +api/