From 9353afec997696e837c0eedb9c8d0d5e48d4653c Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Tue, 27 Jun 2023 09:38:20 +0200 Subject: [PATCH 1/5] Initial Sphinx support --- .readthedocs.yaml | 13 ++++ docs/.gitignore | 162 ++++++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 29 ++++++++ docs/index.md | 14 ++++ docs/pyproject.toml | 25 +++++++ 5 files changed, 243 insertions(+) create mode 100644 .readthedocs.yaml create mode 100644 docs/.gitignore create mode 100644 docs/conf.py create mode 100644 docs/index.md create mode 100644 docs/pyproject.toml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..ffba68da5e --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +python: + install: + - path: docs + extra_requirements: + - docs +build: + os: ubuntu-22.04 + tools: + python: "3.11" +sphinx: + configuration: docs/conf.py diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..287a2f0fe9 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,162 @@ +### Python template +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/#use-with-ide +.pdm.toml + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..8e161469c5 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,29 @@ +project = 'Catch2' +copyright = '2023, Martin Hořeňovský' +author = 'Martin Hořeňovský' + +extensions = [ + "myst_parser", + "sphinx_design", + "sphinx_togglebutton", + "breathe", +] + +templates_path = [] +exclude_patterns = [ + 'build', + '_build', + 'Thumbs.db', + '.DS_Store', + "Readme.md", +] +source_suffix = [".md"] + + +html_theme = 'furo' +#html_static_path = ['_static'] + +myst_enable_extensions = [ + "tasklist", + "colon_fence", +] diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..e2383a8158 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,14 @@ +# Catch2 + +A modern, C++-native, test framework for unit-tests, TDD and BDD - using C++14, C++17 and later. + + +:::{toctree} +--- +maxdepth: 2 +titlesonly: true +caption: Contents +glob: true +--- +/* +::: diff --git a/docs/pyproject.toml b/docs/pyproject.toml new file mode 100644 index 0000000000..641cc5b3ca --- /dev/null +++ b/docs/pyproject.toml @@ -0,0 +1,25 @@ +[build-system] +requires = ["setuptools"] +build-backend = "setuptools.build_meta" + +[project] +name = "Catch2-dev" +version = "0.0.0" +description = "Development environment for Catch2" + + +[project.optional-dependencies] +docs = [ + "sphinx >= 6.0", + "furo", + "sphinx-design", + "sphinx-togglebutton", + "myst-parser", + "breathe", +] +dev = [ + "pre-commit", +] + +[tool.setuptools] +packages = [] From 751e39c35bbf5fd34d9167558070851cbb68ee01 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Tue, 27 Jun 2023 11:16:09 +0200 Subject: [PATCH 2/5] Add doxygen and graphviz support --- .readthedocs.yaml | 3 +++ Doxyfile | 6 +++--- docs/conf.py | 27 +++++++++++++++++++++++++-- 3 files changed, 31 insertions(+), 5 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index ffba68da5e..5ae534d9f6 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -7,6 +7,9 @@ python: - docs build: os: ubuntu-22.04 + apt_packages: + - doxygen + - graphviz tools: python: "3.11" sphinx: diff --git a/Doxyfile b/Doxyfile index 07b385ec10..a1143702be 100644 --- a/Doxyfile +++ b/Doxyfile @@ -57,7 +57,7 @@ PROJECT_BRIEF = "Popular C++ unit testing framework" # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = docs/doxygen +OUTPUT_DIRECTORY = docs/build/doxygen # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -1088,7 +1088,7 @@ IGNORE_PREFIX = # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. -GENERATE_HTML = YES +GENERATE_HTML = NO # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1946,7 +1946,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = NO +GENERATE_XML = YES # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of diff --git a/docs/conf.py b/docs/conf.py index 8e161469c5..37d16f2f84 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,3 +1,9 @@ +import os +import subprocess + +from sphinx.application import Sphinx +from pathlib import Path + project = 'Catch2' copyright = '2023, Martin Hořeňovský' author = 'Martin Hořeňovský' @@ -19,11 +25,28 @@ ] source_suffix = [".md"] - html_theme = 'furo' -#html_static_path = ['_static'] +# html_static_path = ['_static'] myst_enable_extensions = [ "tasklist", "colon_fence", ] + +breathe_projects = { + "Catch2": "build/doxygen/xml", +} +breathe_default_project = "Catch2" + + +def generate_doxygen_xml(app: Sphinx): + """ + Run the doxygen commands + """ + os.chdir(Path(app.confdir).parent) + subprocess.run(["doxygen"]) + + +def setup(app: Sphinx): + # Add hook for building doxygen xml when needed + app.connect("builder-inited", generate_doxygen_xml) From c9d242acb1097f60f579bbab60b6a59dd7a8c314 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Tue, 27 Jun 2023 11:31:41 +0200 Subject: [PATCH 3/5] Add all doxygen API to developer's api --- docs/developer_api/index.md | 10 ++++++++++ docs/index.md | 1 + 2 files changed, 11 insertions(+) create mode 100644 docs/developer_api/index.md diff --git a/docs/developer_api/index.md b/docs/developer_api/index.md new file mode 100644 index 0000000000..3ee528ee41 --- /dev/null +++ b/docs/developer_api/index.md @@ -0,0 +1,10 @@ +# Developer's API + +This is a placeholder for all generated APIs. + +These should be organized using [doxygen groups](https://www.doxygen.nl/manual/grouping.html). + +## All APIs + +:::{doxygenindex} +::: diff --git a/docs/index.md b/docs/index.md index e2383a8158..2d063e3a69 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,5 +10,6 @@ titlesonly: true caption: Contents glob: true --- +developer_api/index /* ::: From c0c2686b0fd3d0051d5724d8f605f7f8b0f1430d Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Tue, 27 Jun 2023 11:35:39 +0200 Subject: [PATCH 4/5] Simplify the gitignore --- docs/.gitignore | 155 +----------------------------------------------- 1 file changed, 1 insertion(+), 154 deletions(-) diff --git a/docs/.gitignore b/docs/.gitignore index 287a2f0fe9..8b72120668 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,162 +1,9 @@ ### Python template -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python build/ -develop-eggs/ -dist/ -downloads/ eggs/ .eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ *.egg-info/ -.installed.cfg *.egg -MANIFEST - -# PyInstaller -# Usually these files are written by a python script from a template -# before PyInstaller builds the exe, so as to inject date/other infos into it. -*.manifest -*.spec - -# Installer logs -pip-log.txt -pip-delete-this-directory.txt - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# Translations -*.mo -*.pot - -# Django stuff: -*.log -local_settings.py -db.sqlite3 -db.sqlite3-journal - -# Flask stuff: -instance/ -.webassets-cache - -# Scrapy stuff: -.scrapy # Sphinx documentation -docs/_build/ - -# PyBuilder -.pybuilder/ -target/ - -# Jupyter Notebook -.ipynb_checkpoints - -# IPython -profile_default/ -ipython_config.py - -# pyenv -# For a library or package, you might want to ignore these files since the code is -# intended to run in multiple environments; otherwise, check them in: -# .python-version - -# pipenv -# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. -# However, in case of collaboration, if having platform-specific dependencies or dependencies -# having no cross-platform support, pipenv may install dependencies that don't work, or not -# install all needed dependencies. -#Pipfile.lock - -# poetry -# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. -# This is especially recommended for binary packages to ensure reproducibility, and is more -# commonly ignored for libraries. -# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control -#poetry.lock - -# pdm -# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. -#pdm.lock -# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it -# in version control. -# https://pdm.fming.dev/#use-with-ide -.pdm.toml - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Celery stuff -celerybeat-schedule -celerybeat.pid - -# SageMath parsed files -*.sage.py - -# Environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Spyder project settings -.spyderproject -.spyproject - -# Rope project settings -.ropeproject - -# mkdocs documentation -/site - -# mypy -.mypy_cache/ -.dmypy.json -dmypy.json - -# Pyre type checker -.pyre/ - -# pytype static type analyzer -.pytype/ - -# Cython debug symbols -cython_debug/ - -# PyCharm -# JetBrains specific template is maintained in a separate JetBrains.gitignore that can -# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore -# and can be added to the global gitignore or merged into this file. For a more nuclear -# option (not recommended) you can uncomment the following to ignore the entire idea folder. -#.idea/ - +_build/ From afe0ca2edc3b9f4e1c0c51054fd16a3d34331b9b Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Tue, 27 Jun 2023 11:44:19 +0200 Subject: [PATCH 5/5] Synchronize the top-page --- README.md | 3 +++ docs/index.md | 9 ++++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3ea54a5d2c..b82c3e41ac 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ [![Try online](https://img.shields.io/badge/try-online-blue.svg)](https://godbolt.org/z/EdoY15q9G) [![Join the chat in Discord: https://discord.gg/4CWS9zD](https://img.shields.io/badge/Discord-Chat!-brightgreen.svg)](https://discord.gg/4CWS9zD) + ## What is Catch2? @@ -101,3 +102,5 @@ This documentation comprises these three parts: * For discussion or questions please use [our Discord](https://discord.gg/4CWS9zD) * See who else is using Catch2 in [Open Source Software](docs/opensource-users.md#top) or [commercially](docs/commercial-users.md#top). + + diff --git a/docs/index.md b/docs/index.md index 2d063e3a69..d25d303aea 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,12 +2,19 @@ A modern, C++-native, test framework for unit-tests, TDD and BDD - using C++14, C++17 and later. +:::{include} ../README.md +--- +start-after: +end-before: +--- +::: + +## Contents :::{toctree} --- maxdepth: 2 titlesonly: true -caption: Contents glob: true --- developer_api/index