Edit readme in cpp-example and remove api file from exhale
This commit is contained in:
parent
70e39d375e
commit
3de073ba4a
13 changed files with 132 additions and 183 deletions
20
Makefile
Normal file
20
Makefile
Normal 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)
|
||||||
1
cpp-example/docs/.gitignore
vendored
1
cpp-example/docs/.gitignore
vendored
|
|
@ -1 +1,2 @@
|
||||||
build/
|
build/
|
||||||
|
source/api
|
||||||
|
|
@ -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:
|
|
||||||
|
|
@ -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
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -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`
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -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`
|
|
||||||
|
|
||||||
|
|
@ -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
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -1,10 +0,0 @@
|
||||||
===========
|
|
||||||
Library API
|
|
||||||
===========
|
|
||||||
|
|
||||||
.. include:: class_view_hierarchy.rst.include
|
|
||||||
|
|
||||||
.. include:: file_view_hierarchy.rst.include
|
|
||||||
|
|
||||||
.. include:: unabridged_api.rst.include
|
|
||||||
|
|
||||||
|
|
@ -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;
|
|
||||||
};
|
|
||||||
|
|
@ -1,12 +0,0 @@
|
||||||
|
|
||||||
Full API
|
|
||||||
--------
|
|
||||||
|
|
||||||
Classes and Structs
|
|
||||||
*******************
|
|
||||||
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 5
|
|
||||||
|
|
||||||
classDriver.rst
|
|
||||||
|
|
@ -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
|
|
||||||
|
|
@ -1,19 +1,86 @@
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
# Sphinx documentation for C / C++
|
# Sphinx documentation from c/c++ doxygen doc
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
## :wrench: Dependencies installation
|
## :tv: Demo
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
pip3 install sphinx breathe exhale
|
# Installing dependencies
|
||||||
|
pip3 install sphinx shibuya breathe exhale
|
||||||
sudo apt-get install doxygen
|
sudo apt-get install doxygen
|
||||||
```
|
|
||||||
|
|
||||||
## :rocket: Générer la documentation
|
# Generating documentation
|
||||||
|
|
||||||
```sh
|
|
||||||
cd docs
|
cd docs
|
||||||
make html
|
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
35
make.bat
Normal 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
|
||||||
Loading…
Reference in a new issue