From 3de073ba4a33559a6be85411fd5a050142ed1aa0 Mon Sep 17 00:00:00 2001 From: Foucher Alexandre Date: Wed, 24 Jan 2024 11:25:40 +0100 Subject: [PATCH] Edit readme in cpp-example and remove api file from exhale --- Makefile | 20 +++++ cpp-example/docs/.gitignore | 3 +- 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/readme.md | 83 +++++++++++++++++-- make.bat | 35 ++++++++ 13 files changed, 132 insertions(+), 183 deletions(-) create mode 100644 Makefile delete mode 100644 cpp-example/docs/source/api/classDriver.rst delete mode 100644 cpp-example/docs/source/api/class_view_hierarchy.rst.include delete mode 100644 cpp-example/docs/source/api/dir__home_alexandre_Documents_test-sphinx_cpp-example_include.rst delete mode 100644 cpp-example/docs/source/api/file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst delete mode 100644 cpp-example/docs/source/api/file_view_hierarchy.rst.include delete mode 100644 cpp-example/docs/source/api/library_root.rst delete mode 100644 cpp-example/docs/source/api/program_listing_file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst delete mode 100644 cpp-example/docs/source/api/unabridged_api.rst.include delete mode 100644 cpp-example/docs/source/api/unabridged_orphan.rst create mode 100644 make.bat diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/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 = source +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/cpp-example/docs/.gitignore b/cpp-example/docs/.gitignore index d163863..2acb705 100644 --- a/cpp-example/docs/.gitignore +++ b/cpp-example/docs/.gitignore @@ -1 +1,2 @@ -build/ \ No newline at end of file +build/ +source/api \ No newline at end of file diff --git a/cpp-example/docs/source/api/classDriver.rst b/cpp-example/docs/source/api/classDriver.rst deleted file mode 100644 index 9c400e2..0000000 --- a/cpp-example/docs/source/api/classDriver.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _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 deleted file mode 100644 index d1e51dd..0000000 --- a/cpp-example/docs/source/api/class_view_hierarchy.rst.include +++ /dev/null @@ -1,18 +0,0 @@ - -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 deleted file mode 100644 index 9cc2270..0000000 --- a/cpp-example/docs/source/api/dir__home_alexandre_Documents_test-sphinx_cpp-example_include.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _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 deleted file mode 100644 index 904fcfc..0000000 --- a/cpp-example/docs/source/api/file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst +++ /dev/null @@ -1,39 +0,0 @@ - -.. _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 deleted file mode 100644 index 45a079d..0000000 --- a/cpp-example/docs/source/api/file_view_hierarchy.rst.include +++ /dev/null @@ -1,18 +0,0 @@ - -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 deleted file mode 100644 index 1936b1f..0000000 --- a/cpp-example/docs/source/api/library_root.rst +++ /dev/null @@ -1,10 +0,0 @@ -=========== -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 deleted file mode 100644 index c914c88..0000000 --- a/cpp-example/docs/source/api/program_listing_file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.rst +++ /dev/null @@ -1,21 +0,0 @@ - -.. _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 deleted file mode 100644 index 2b067ca..0000000 --- a/cpp-example/docs/source/api/unabridged_api.rst.include +++ /dev/null @@ -1,12 +0,0 @@ - -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 deleted file mode 100644 index 466cb7d..0000000 --- a/cpp-example/docs/source/api/unabridged_orphan.rst +++ /dev/null @@ -1,23 +0,0 @@ -: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/readme.md b/cpp-example/readme.md index 34818e1..6ae5cd4 100644 --- a/cpp-example/readme.md +++ b/cpp-example/readme.md @@ -1,19 +1,86 @@
-# Sphinx documentation for C / C++ +# Sphinx documentation from c/c++ doxygen doc
-## :wrench: Dependencies installation +## :tv: Demo ```sh -pip3 install sphinx breathe exhale +# Installing dependencies +pip3 install sphinx shibuya breathe exhale sudo apt-get install doxygen -``` -## :rocket: Générer la documentation - -```sh +# Generating documentation cd docs make html -``` \ No newline at end of file +``` + +You can acces it through `docs/build/html/index.html`. + +## :rocket: How to use it ? + +**1. Generate the sphinx structure** + +In a first place, you need to generate the sphinx documentation using +the command `sphinx-quickstart` inside a `docs` folder as below : + +```sh +mkdir docs +cd docs +sphinx-quickstart --sep -l "fr" -r 1.0 . +``` + +Now your project structure should look like this + +``` +my_project/ +├── docs/ +│ ├── build/ +│ ├── source/ +│ ├── conf.py +│ ├── make.bat +│ └── Makefie +├── src +└── readme.md +``` + +**2. Edit sphinx config** + +And lastly you need to copy the next script at the end of the `conf.py` file. +This script add the needed configuration to allow sphinx to generate the documentation from doxygen documentation inside `.h`,`.c`,`.cpp`,`.hpp`... (You don't need to change anything in the next configuration) + +```py +extensions += ['breathe','exhale'] + +breathe_projects = {"My Project": "../build/_doxygen/xml"} +breathe_default_project = "My Project" + +exhale_args = { + "containmentFolder": "./api", + "rootFileName": "library_root.rst", + "doxygenStripFromPath": "..", + "rootFileTitle": "Library API", + "createTreeView": True, + "exhaleExecutesDoxygen": True, + "exhaleDoxygenStdin": "INPUT = ../../include" +} +``` + +**3. Link the doc to a toctree** + +Now you need to link the documentation somewhere in your sphinx `rst` file. +The best way is to go in `source/index.rst` and add `api/library_root` as an entry of the toctree. + +```css +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + api/library_root +``` + +**4. Now you can generate !** + +Inside the `docs` directory you can now execute `make html` ! +You can acces it through `docs/build/html/index.html`. \ No newline at end of file diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +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