Edit readme in cpp-example and remove api file from exhale

This commit is contained in:
Alexandre Foucher 2024-01-24 11:25:40 +01:00
parent 70e39d375e
commit 3de073ba4a
13 changed files with 132 additions and 183 deletions

20
Makefile Normal file
View file

@ -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)

View file

@ -1 +1,2 @@
build/
source/api

View file

@ -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:

View file

@ -1,18 +0,0 @@
Class Hierarchy
---------------
.. raw:: html
<ul class="treeView" id="class-treeView">
<li>
<ul class="collapsibleList">
<li class="lastChild">Class <a href="classDriver.html#exhale-class-classDriver">Driver</a></li>
</ul>
</li><!-- only tree view element -->
</ul><!-- /treeView class-treeView -->
.. end raw html for treeView

View file

@ -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`

View file

@ -1,39 +0,0 @@
.. _file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h:
File Driver.h
=============
|exhale_lsh| :ref:`Parent directory <dir__home_alexandre_Documents_test-sphinx_cpp-example_include>` (``/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`

View file

@ -1,18 +0,0 @@
File Hierarchy
--------------
.. raw:: html
<ul class="treeView" id="file-treeView">
<li>
<ul class="collapsibleList">
<li class="lastChild">Directory <a href="dir__home_alexandre_Documents_test-sphinx_cpp-example_include.html#dir-home-alexandre-Documents-test-sphinx-cpp-example-include">include</a><ul><li class="lastChild">File <a href="file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h.html#file-home-alexandre-Documents-test-sphinx-cpp-example-include-Driver.h">Driver.h</a></li></ul></li>
</ul>
</li><!-- only tree view element -->
</ul><!-- /treeView file-treeView -->
.. end raw html for treeView

View file

@ -1,10 +0,0 @@
===========
Library API
===========
.. include:: class_view_hierarchy.rst.include
.. include:: file_view_hierarchy.rst.include
.. include:: unabridged_api.rst.include

View file

@ -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 <file__home_alexandre_Documents_test-sphinx_cpp-example_include_Driver.h>` (``/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;
};

View file

@ -1,12 +0,0 @@
Full API
--------
Classes and Structs
*******************
.. toctree::
:maxdepth: 5
classDriver.rst

View file

@ -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

View file

@ -1,19 +1,86 @@
<div align="center">
# Sphinx documentation for C / C++
# Sphinx documentation from c/c++ doxygen doc
</div>
## :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
```
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`.

35
make.bat Normal file
View file

@ -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