-
Notifications
You must be signed in to change notification settings - Fork 26
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Automatic C++ documentation generation (#8)
* updated requirements.txt for building docs * removed files from demo into main doc directory * added RTD config file * Update .readthedocs.yaml * Updated python version to 3.8 * added required changes to build doxygen output using doxygen * removed all requirements for docs * removed command from doxygen call * changed directory of command for doxygen * reverted last changes and set output to build * set the doxygen output dir to the current working directory * added descriptors to the classes and updated README * removed docs build pipeline from CMake * removed files for demo * set HIDE_UNDOC_MEMBERS to False * removed README.md from tests * updated some docstrings and converted demo to md file * added missing demo folder * replaced text tables with md tables * removed addition of demo\ from this PR * added undoc classes and included source files for doxygen * removed modules by removing the 'defgroup' parameter from docstrings * Update README.md * re-added the images directory containing the teaser * Updated link to new RTD site * updates doxygent to include teaser img on index page + minor adjustment * moved mainpage docstring to its own file * Update src/Core/GUI/VRInterface.hpp Co-authored-by: Christian Richardt <[email protected]> * Update src/Core/CameraSetup/CameraSetupVisualization.hpp Co-authored-by: Christian Richardt <[email protected]> * Update docs/README.md Co-authored-by: Christian Richardt <[email protected]> * Update src/Core/Geometry/PointCloud.hpp Co-authored-by: Christian Richardt <[email protected]> * Update src/Core/Geometry/Sphere.hpp Co-authored-by: Christian Richardt <[email protected]> * updated placement of docstrings * Update src/Core/Geometry/Circle.hpp Co-authored-by: Christian Richardt <[email protected]> * Update src/Core/Geometry/Circle.hpp Co-authored-by: Christian Richardt <[email protected]> * Update src/Core/Geometry/Cylinder.hpp Co-authored-by: Christian Richardt <[email protected]> * moved mainpage to src and fixed viewerapp docstring * Update src/Core/Application.hpp Co-authored-by: Christian Richardt <[email protected]> * Update src/Core/CameraSetup/CameraSetupVisualization.hpp Co-authored-by: Christian Richardt <[email protected]> * Update src/Core/GL/GLRenderable.hpp Co-authored-by: Christian Richardt <[email protected]> * Update src/Core/GL/GLRenderable.hpp Co-authored-by: Christian Richardt <[email protected]> * removed confusing documentation * Update src/Core/GL/GLApplication.hpp Co-authored-by: Christian Richardt <[email protected]> * Apply suggestions from code review Co-authored-by: Christian Richardt <[email protected]> * updated docs in geometry * re-added deleted images * fixing todos on PR #8 * adding missing documentation * Clean up pass * Tweak location of docs badge * Undo previous commit * made doxygen show private class members * fixed todos for PR #8 * re-added empty index.rst file * Clean-up pass * Update README.md Co-authored-by: rjl67 <[email protected]> Co-authored-by: Christian Richardt <[email protected]>
- Loading branch information
3 people
authored
Jul 8, 2021
1 parent
faba49c
commit 0e4c026
Showing
34 changed files
with
283 additions
and
418 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| # .readthedocs.yaml | ||
| # Read the Docs configuration file | ||
| # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details | ||
|
|
||
| # Required | ||
| version: 2 | ||
|
|
||
| # Build documentation in the docs/ directory with Sphinx | ||
| sphinx: | ||
| configuration: docs/conf.py | ||
|
|
||
| # Optionally build your docs in additional formats such as PDF | ||
| formats: | ||
|
|
||
| # Optionally set the version of Python and requirements required to build your docs | ||
| python: | ||
| version: 3.8 | ||
| install: | ||
| - requirements: docs/requirements.txt |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,50 +1,97 @@ | ||
| # Documentation | ||
| # Building Documentation | ||
|
|
||
| To build the documentation, you'll first of all need to have installed doxygen and make it available on your path. | ||
| To check this, run this command and make sure it does not return an error: | ||
| To build the documentation, you will need to have [installed doxygen](https://www.doxygen.nl/download.html) (making it available on your path). | ||
| [The installation instructions](https://www.doxygen.nl/manual/install.html) could be helpful as well. | ||
| To check that doxygen is on your path, run this command and make sure it does not return an error: | ||
|
|
||
| doxygen --version | ||
|
|
||
| Secondly, you'll need to have installed the sphinx packages in the `requirements.txt` file in this directory. | ||
| To do this, generate and activate a Python environment and install the requirements: | ||
| Then run the command | ||
|
|
||
| doxygen | ||
|
|
||
| python -m venv sphinxenv | ||
| sphinxenv/Scripts/activate (windows) | ||
| source sphinx/bin/activate (linux) | ||
| pip install -r requirements.txt | ||
| or | ||
|
|
||
| Then run the CMake GUI from the terminal, with the Python env activated: | ||
| doxygen Doxyfile | ||
|
|
||
| cmake-gui | ||
| in the `docs/` directory. | ||
|
|
||
| Set the `WITH_DOCS` flag to true in the CMake GUI, then hit configure + generate. | ||
| Build, successively, the doxygen project and then the sphinx project. | ||
|
|
||
| **NOTE:** The sphinx project will fail its build if doxygen isn't built first. | ||
| If you do not, the Docs section (that uses doxygen) will display a warning of the form: | ||
| ## Read the Docs | ||
|
|
||
| ``` | ||
| !Warning | ||
| oxygenclass: breathe_default_project value ‘OmniPhotos’ does not seem to be a valid key for the breathe_projects dictionary | ||
| ``` | ||
| Read the Docs virtual machines read the [sphinx](https://www.sphinx-doc.org/) `conf.py` file and generate the documentation accordingly. | ||
| We have injected the call to doxygen into this file. | ||
| The doxygen binary is then executed in the docs directory and generates files in the `docs/html/` directory, replacing the generated sphinx html files with those build by doxygen. | ||
|
|
||
| The Doxyfile.in is where you want to make your modifications to the html/xml output from Doxygen. | ||
| This will be copied over and filled in by CMake at build time. | ||
| To switch this on or off the html generation for doxygen set the `GENERATE_HTML` flag in `Doxyfile.in` and run the configure + generate pipeline again. | ||
| There is also a `HIDE_UNDOC_CLASSES` that will reduce the build time if set to "yes". | ||
| If you want the standard doxygen HTML files with all the classes, then set this flag to "no" as well as the `GENERATE_HTML` flag to "yes". | ||
| The latest generated code documentation is available at https://omniphotos.readthedocs.io/en/latest/. | ||
|
|
||
| To run the Doxygen section of the build on its own, run the following command in | ||
| the `build/docs` directory once you've run CMake: | ||
|
|
||
| doxygen ..build/docs/doxygen/Doxyfile | ||
| # Writing Documentation | ||
|
|
||
| In order to run the sphinx build step independently (once you've run the doxygen step successfully), run the following command from the `docs` directory: | ||
|
|
||
| sphinx-build -E -b html -Dbreathe_projects.OmniPhotos=../build/docs/doxygen/xml . ../build/docs/sphinx | ||
| ## Getting started | ||
|
|
||
| In order to create a doxygen code stump, one can use the **Doxygen Comments** extension found in the Visual Studio online extension manager. | ||
| It is not necessary to use this, but it seems to be the easiest option: | ||
|
|
||
| <img src='images/vs_screenshot_1.png'/> | ||
|
|
||
| The extension will generate a stub whenever you type `/**` and press enter above a function, variable or class. | ||
|
|
||
| The stumps can be customized via Tools->Options and selecting Doxygen in the left-hand pane. | ||
|
|
||
| **Other Option:** | ||
| Use the Visual Studio Plugin **1-Click Docs**. | ||
| You can use the **1-Click Docs** extension to call `doxygen.exe` in Visual Studio. | ||
| For more information please refer to https://www.doxygen.nl/manual/starting.html. | ||
|
|
||
| There is a demo project (https://github.com/yuanmingze/codestyle_demo) for Doxygen use. | ||
|
|
||
|
|
||
| ## Doxygen Conventions | ||
|
|
||
| ### 1. C/C++ | ||
|
|
||
| All documentation for classes should be located in the header files. | ||
|
|
||
| The convention that has been used for the documentation has been the javadoc style: | ||
|
|
||
| /** | ||
| * A brief history of JavaDoc-style (C-style) comments. | ||
| * | ||
| * This is the typical JavaDoc-style C-style comment. It starts with two | ||
| * asterisks. | ||
| * | ||
| * @param theory Even if there is only one possible unified theory. it is just | ||
| * a set of rules and equations. | ||
| */ | ||
| void cstyle(int theory); | ||
|
|
||
| The source code and further elaboration on this style can be found here: | ||
| https://www.doxygen.nl/manual/docblocks.html | ||
|
|
||
| Each class method should have a documentation string one line above it, as shown above. | ||
| The description for the function should be succinct and define what purpose of the function, the @param that are being used and why it is there. | ||
| If there is a @return value, this should be explained here as well. | ||
| The “@” symbol has been used to designate the fields. | ||
|
|
||
| Single line comments should be added before class variables as well: | ||
|
|
||
| /** List of supported rendering methods. */ | ||
| std::vector<std::string> methods; | ||
|
|
||
| Note that for a class to appear as "documented" in the "Class Index" list and "Class Hiearchy" lists in Doxygen, one needs to add a `@brief` descriptor in the line directly before the class declaration (in the header). | ||
|
|
||
| /** | ||
| * @brief This is a class for ... | ||
| */ | ||
| class MyClass | ||
| { | ||
| } | ||
| The `@brief` notation is not strictly necessary here, but might be important to be explicit. | ||
|
|
||
|
|
||
| ### 2. Python | ||
|
|
||
| **NOTE:** | ||
| - `-E` here tells sphinx to rebuild everything, no matter what (i.e does not do an incremental build) | ||
| - `-D` overrides the specified value in `conf.py` for var `breathe_projects.OmniPhotos` | ||
| - the last two arguments are positional for source and build dir respectively. | ||
| The convention of coding is based on the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). | ||
|
|
||
| If you use Visual Studio Code, please refer to the official guide to configure the [automatic linting functionality](https://code.visualstudio.com/docs/python/linting). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.