From d855b4680dc9cbe6001b6af01b8f2344f820d371 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 4425383aaa589d5e1f1888bf164e86c4bcf98c1e 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 c33c7e362e..9dca9273cd 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 e84d61cb64f410ab36517aafe4fbecfe2e3f5e5e 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 633a081c7e6b49d08de2cd017f09597fedc57d23 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 1305581114ee24673c1276d4edc44de78f28e613 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 9dca9273cd..605f6f86c5 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 d50daedccace24bf69903ff7879bc0543757f5ef 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 5158bd8ac8cd2ae76c8c4b3adc26639a953a9485 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 1c693d4371fee863cd697a9a891b0eb5ee2480c9 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 605f6f86c5..aa22691ba5 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 9bca03a2b2fb84a3fac2820bda5a41d8c680e869 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 434fc5ecbdfb9392ee76ccea2e8cc097a3710c37 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 9251ed55a8b4e3f878dfe0416d056d6c30f7fece 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 c1f2eef43a46ae59571526871d28ee7453d63d7c 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 2717f622b8afd2c026e270f638d01e2320d339b1 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/