docs: Sphinx + ReadTheDocs

.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

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

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)
 
+<!-- SPHINX-START -->
 
 ## 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).
+
+<!-- SPHINX-END -->

docs/.gitignore

@@ -0,0 +1,9 @@
+### Python template
+build/
+eggs/
+.eggs/
+*.egg-info/
+*.egg
+
+# Sphinx documentation
+_build/

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)

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}
+:::

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: <!-- SPHINX-START -->
+end-before: <!-- SPHINX-END -->
+---
+:::
+
+## Contents
+
+:::{toctree}
+---
+maxdepth: 2
+titlesonly: true
+glob: true
+---
+developer_api/index
+/*
+:::

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 = []