diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..5ae534d9f6 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,16 @@ +version: 2 + +python: + install: + - path: docs + extra_requirements: + - docs +build: + os: ubuntu-22.04 + apt_packages: + - doxygen + - graphviz + tools: + python: "3.11" +sphinx: + configuration: docs/conf.py 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/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/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..8b72120668 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,9 @@ +### Python template +build/ +eggs/ +.eggs/ +*.egg-info/ +*.egg + +# Sphinx documentation +_build/ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..37d16f2f84 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,52 @@ +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ý' + +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", +] + +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) 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 new file mode 100644 index 0000000000..d25d303aea --- /dev/null +++ b/docs/index.md @@ -0,0 +1,22 @@ +# Catch2 + +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 +glob: true +--- +developer_api/index +/* +::: 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 = []