From 8dfcbf83f56dc37c683418f85d1387c4e5a93cf2 Mon Sep 17 00:00:00 2001 From: Foucher Alexandre Date: Tue, 23 Jan 2024 17:07:41 +0100 Subject: [PATCH] Working cpp documentation breathe + exhale --- cpp-example/docs/Doxyfile.in | 10 ---- cpp-example/docs/Makefile | 8 ++- cpp-example/docs/conf.py | 12 ----- cpp-example/docs/cpp-reference/driver.h.rst | 9 ---- cpp-example/docs/cpp-reference/index.rst | 13 ----- cpp-example/docs/make.bat | 4 +- cpp-example/docs/source/api/classDriver.rst | 17 +++++++ .../api/class_view_hierarchy.rst.include | 18 +++++++ ...uments_test-sphinx_cpp-example_include.rst | 16 ++++++ ...st-sphinx_cpp-example_include_Driver.h.rst | 39 +++++++++++++++ .../api/file_view_hierarchy.rst.include | 18 +++++++ cpp-example/docs/source/api/library_root.rst | 10 ++++ ...st-sphinx_cpp-example_include_Driver.h.rst | 21 ++++++++ .../source/api/unabridged_api.rst.include | 12 +++++ .../docs/source/api/unabridged_orphan.rst | 23 +++++++++ cpp-example/docs/source/conf.py | 49 +++++++++++++++++++ cpp-example/docs/{ => source}/index.rst | 11 ++--- 17 files changed, 232 insertions(+), 58 deletions(-) delete mode 100644 cpp-example/docs/Doxyfile.in delete mode 100644 cpp-example/docs/conf.py delete mode 100644 cpp-example/docs/cpp-reference/driver.h.rst delete mode 100644 cpp-example/docs/cpp-reference/index.rst mode change 100755 => 100644 cpp-example/docs/make.bat create mode 100644 cpp-example/docs/source/api/classDriver.rst create mode 100644 cpp-example/docs/source/api/class_view_hierarchy.rst.include create mode 100644 cpp-example/docs/source/api/dir__home_alexandre_Documents_test-sphinx_cpp-example_include.rst create mode 100644 cpp-example/docs/source/api/file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst create mode 100644 cpp-example/docs/source/api/file_view_hierarchy.rst.include create mode 100644 cpp-example/docs/source/api/library_root.rst create mode 100644 cpp-example/docs/source/api/program_listing_file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst create mode 100644 cpp-example/docs/source/api/unabridged_api.rst.include create mode 100644 cpp-example/docs/source/api/unabridged_orphan.rst create mode 100644 cpp-example/docs/source/conf.py rename cpp-example/docs/{ => source}/index.rst (56%) diff --git a/cpp-example/docs/Doxyfile.in b/cpp-example/docs/Doxyfile.in deleted file mode 100644 index e6d6f27..0000000 --- a/cpp-example/docs/Doxyfile.in +++ /dev/null @@ -1,10 +0,0 @@ -# Doxyfile 1.8.17 - -PROJECT_NAME = "my_project" -INPUT = ../include -INPUT_ENCODING = UTF-8 -RECURSIVE = YES -GENERATE_XML = YES -XML_OUTPUT = build/doxyxml -GENERATE_LATEX = NO -GENERATE_HTML = NO \ No newline at end of file diff --git a/cpp-example/docs/Makefile b/cpp-example/docs/Makefile index 9ba79d3..d0c3cbf 100644 --- a/cpp-example/docs/Makefile +++ b/cpp-example/docs/Makefile @@ -5,18 +5,16 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build -SOURCEDIR = . +SOURCEDIR = source BUILDDIR = build # Put it first so that "make" without argument is like "make help". -# help: -# @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +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 - @mkdir -p build - @doxygen ./Doxyfile.in @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/cpp-example/docs/conf.py b/cpp-example/docs/conf.py deleted file mode 100644 index 1cee903..0000000 --- a/cpp-example/docs/conf.py +++ /dev/null @@ -1,12 +0,0 @@ -from cgitb import html - -extensions = ["breathe"] - -html_theme = "shibuya" - -html_theme_options = { - "globaltoc_expand_depth": 1, -} - -breathe_projects = {"my_project": "build/doxyxml/"} -breathe_default_project = "my_project" \ No newline at end of file diff --git a/cpp-example/docs/cpp-reference/driver.h.rst b/cpp-example/docs/cpp-reference/driver.h.rst deleted file mode 100644 index 1c2001d..0000000 --- a/cpp-example/docs/cpp-reference/driver.h.rst +++ /dev/null @@ -1,9 +0,0 @@ -driver.h -======== - -.. - doxygenfile:: driver.h - -.. doxygenfunction:: add - :project: my_project - :sections: parameters diff --git a/cpp-example/docs/cpp-reference/index.rst b/cpp-example/docs/cpp-reference/index.rst deleted file mode 100644 index 7fe855c..0000000 --- a/cpp-example/docs/cpp-reference/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -Reference -========= - -ROS est un méta-système d'exploitation à code source ouvert pour votre robot. Il fournit les services que vous attendez d'un système d'exploitation, notamment l'abstraction matérielle, le contrôle des périphériques de bas niveau, la mise en œuvre des fonctionnalités les plus courantes, le passage de messages entre les processus et la gestion des paquets. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - driver.h - -Lancement ---------- \ No newline at end of file diff --git a/cpp-example/docs/make.bat b/cpp-example/docs/make.bat old mode 100755 new mode 100644 index c556664..747ffb7 --- a/cpp-example/docs/make.bat +++ b/cpp-example/docs/make.bat @@ -7,7 +7,7 @@ REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) -set SOURCEDIR=. +set SOURCEDIR=source set BUILDDIR=build %SPHINXBUILD% >NUL 2>NUL @@ -25,8 +25,6 @@ if errorlevel 9009 ( if "%1" == "" goto help -mkdir build 2>nul -doxygen ./Doxyfile.in %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% goto end diff --git a/cpp-example/docs/source/api/classDriver.rst b/cpp-example/docs/source/api/classDriver.rst new file mode 100644 index 0000000..9c400e2 --- /dev/null +++ b/cpp-example/docs/source/api/classDriver.rst @@ -0,0 +1,17 @@ +.. _exhale_class_classDriver: + +Class Driver +============ + +- Defined in :ref:`file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h` + + +Class Documentation +------------------- + + +.. doxygenclass:: Driver + :project: My Project + :members: + :protected-members: + :undoc-members: \ No newline at end of file diff --git a/cpp-example/docs/source/api/class_view_hierarchy.rst.include b/cpp-example/docs/source/api/class_view_hierarchy.rst.include new file mode 100644 index 0000000..d1e51dd --- /dev/null +++ b/cpp-example/docs/source/api/class_view_hierarchy.rst.include @@ -0,0 +1,18 @@ + +Class Hierarchy +--------------- + + +.. raw:: html + + + +.. end raw html for treeView + + diff --git a/cpp-example/docs/source/api/dir__home_alexandre_Documents_test-sphinx_cpp-example_include.rst b/cpp-example/docs/source/api/dir__home_alexandre_Documents_test-sphinx_cpp-example_include.rst new file mode 100644 index 0000000..9cc2270 --- /dev/null +++ b/cpp-example/docs/source/api/dir__home_alexandre_Documents_test-sphinx_cpp-example_include.rst @@ -0,0 +1,16 @@ +.. _dir__home_alexandre_Documents_test-sphinx_cpp-example_include: + + +Directory include +================= + + +*Directory path:* ``/home/alexandre/Documents/test-sphinx/cpp-example/include`` + + +Files +----- + +- :ref:`file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h` + + diff --git a/cpp-example/docs/source/api/file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst b/cpp-example/docs/source/api/file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst new file mode 100644 index 0000000..904fcfc --- /dev/null +++ b/cpp-example/docs/source/api/file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst @@ -0,0 +1,39 @@ + +.. _file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h: + +File Driver.h +============= + +|exhale_lsh| :ref:`Parent directory ` (``/home/alexandre/Documents/test-sphinx/cpp-example/include``) + +.. |exhale_lsh| unicode:: U+021B0 .. UPWARDS ARROW WITH TIP LEFTWARDS + + +.. contents:: Contents + :local: + :backlinks: none + +Definition (``/home/alexandre/Documents/test-sphinx/cpp-example/include/Driver.h``) +----------------------------------------------------------------------------------- + + +.. toctree:: + :maxdepth: 1 + + program_listing_file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst + + + + + + + + + + +Classes +------- + + +- :ref:`exhale_class_classDriver` + diff --git a/cpp-example/docs/source/api/file_view_hierarchy.rst.include b/cpp-example/docs/source/api/file_view_hierarchy.rst.include new file mode 100644 index 0000000..45a079d --- /dev/null +++ b/cpp-example/docs/source/api/file_view_hierarchy.rst.include @@ -0,0 +1,18 @@ + +File Hierarchy +-------------- + + +.. raw:: html + + + +.. end raw html for treeView + + diff --git a/cpp-example/docs/source/api/library_root.rst b/cpp-example/docs/source/api/library_root.rst new file mode 100644 index 0000000..1936b1f --- /dev/null +++ b/cpp-example/docs/source/api/library_root.rst @@ -0,0 +1,10 @@ +=========== +Library API +=========== + +.. include:: class_view_hierarchy.rst.include + +.. include:: file_view_hierarchy.rst.include + +.. include:: unabridged_api.rst.include + diff --git a/cpp-example/docs/source/api/program_listing_file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst b/cpp-example/docs/source/api/program_listing_file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst new file mode 100644 index 0000000..c914c88 --- /dev/null +++ b/cpp-example/docs/source/api/program_listing_file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst @@ -0,0 +1,21 @@ + +.. _program_listing_file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h: + +Program Listing for File Driver.h +================================= + +|exhale_lsh| :ref:`Return to documentation for file ` (``/home/alexandre/Documents/test-sphinx/cpp-example/include/Driver.h``) + +.. |exhale_lsh| unicode:: U+021B0 .. UPWARDS ARROW WITH TIP LEFTWARDS + +.. code-block:: cpp + + + class Driver + { + public: + int write(unsigned char *buffer); + + private: + bool mIsActive; + }; diff --git a/cpp-example/docs/source/api/unabridged_api.rst.include b/cpp-example/docs/source/api/unabridged_api.rst.include new file mode 100644 index 0000000..2b067ca --- /dev/null +++ b/cpp-example/docs/source/api/unabridged_api.rst.include @@ -0,0 +1,12 @@ + +Full API +-------- + +Classes and Structs +******************* + + +.. toctree:: + :maxdepth: 5 + + classDriver.rst diff --git a/cpp-example/docs/source/api/unabridged_orphan.rst b/cpp-example/docs/source/api/unabridged_orphan.rst new file mode 100644 index 0000000..466cb7d --- /dev/null +++ b/cpp-example/docs/source/api/unabridged_orphan.rst @@ -0,0 +1,23 @@ +:orphan: + + +Full API +======== + +Directories +*********** + + +.. toctree:: + :maxdepth: 5 + + dir__home_alexandre_Documents_test-sphinx_cpp-example_include.rst + +Files +***** + + +.. toctree:: + :maxdepth: 5 + + file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst diff --git a/cpp-example/docs/source/conf.py b/cpp-example/docs/source/conf.py new file mode 100644 index 0000000..a54f431 --- /dev/null +++ b/cpp-example/docs/source/conf.py @@ -0,0 +1,49 @@ +# 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 + +project = 'cpp-example' +copyright = '2024, Alexandre Foucher' +author = 'Alexandre Foucher' +release = '1.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'breathe', + 'exhale' +] + +breathe_projects = {"My Project": "../build/_doxygen/xml"} +breathe_default_project = "My Project" + +exhale_args = { + # These arguments are required + "containmentFolder": "./api", + "rootFileName": "library_root.rst", + "doxygenStripFromPath": "..", + # Heavily encouraged optional argument (see docs) + "rootFileTitle": "Library API", + # Suggested optional arguments + "createTreeView": True, + # TIP: if using the sphinx-bootstrap-theme, you need + # "treeViewIsBootstrap": True, + "exhaleExecutesDoxygen": True, + "exhaleDoxygenStdin": "INPUT = ../../include" +} + +templates_path = ['_templates'] +exclude_patterns = [] + +language = 'fr' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'shibuya' +html_static_path = ['_static'] diff --git a/cpp-example/docs/index.rst b/cpp-example/docs/source/index.rst similarity index 56% rename from cpp-example/docs/index.rst rename to cpp-example/docs/source/index.rst index 7e3d0d3..49fa7cc 100644 --- a/cpp-example/docs/index.rst +++ b/cpp-example/docs/source/index.rst @@ -1,17 +1,16 @@ -.. test documentation master file, created by - sphinx-quickstart on Fri Jan 19 17:24:42 2024. +.. cpp-example documentation master file, created by + sphinx-quickstart on Tue Jan 23 15:55:27 2024. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to test's documentation! -================================ +Welcome to cpp-example's documentation! +======================================= .. toctree:: :maxdepth: 2 :caption: Contents: - cpp-reference/index - + api/library_root Indices and tables ==================