doxinabox

About the project

Introduction

This project is a Sphinx example/template documentation for embedded software projects in C/C++. For further information about how to generate documentation with Sphinx visit the Sphinx documentation website. Sphinx uses the extension Breathe to import C/C++ code documentation. Visit the Breathe documentation website for further customization of the generated documentation.

Have a look on the example/template documentation by jumping to index.html [/doc/build/html/index.html].

Have a look into the functional-requirements for a listing of all capabilities.

Operation

First time setup

  • Fork the project per github-URL. Visit the git documentation website for further information about how to use git. You may also use “Download ZIP” from the doxinabox github project website.
  • Integrate the virtual environment of doxinabox into your virtualenv environment. Visit the virtualenv documentation website and virtualenvwrapper documentation website for further information about the setup and management of virtual environments. Copy the doxinabox virtual environment [/venv/doxinabox] into your directory containing the virtual environments. The packages may be installed from the requirement file [/venv/doxinabox/requirements.txt].
  • Generate the .xml files with doxygen. The API documentation (section “Code documentation/Production code documentation”) of the template is generated from the example source code [/examplecode]. To generate the .xml files from this example code change into the directory which contains the doxygen configuration file (here: v1.8.9) [/doc/ext/doxygen]. Run doxygen in the shell with doxygen sphinx. The .xml files are placed in the source dierctory of sphinx [/doc/source/xml].
  • (Optional) Replace the Sphinx theme “Read the docs” with a theme of your choice [/doc/source/_themes].
  • Modify the Sphinx configuration file conf.py [/doc/source/]: project name, etc. TODO.
  • Generate the .html project documentation with Sphinx. Change into the root directory of the documentation [/doc] and run make html (with active virtual enviroment “doxinabox”). The .hmtl documentation is placed in [/doc/build/]. All files in this directory may be deleted before generating the next time.
  • Insert the .html documentation [/doc/build/html] into your project directory. Use index.html [/doc/build/html/index.html] as entry point. The automatically generated production source code documentation is located in the section “Code documentation/Production code documentation”.

Contribution

  • Install Python.
  • Install an IDE (e.g. Ninja IDE for Linux from the Ninja IDE website).
  • Get the code like already described.
  • Happy coding...
  • Create a free account on the GitHub website.
  • Install a GUI for Git (e.g. gitg from the gitg website).
  • Happy contributing over GitHub...

Indices and tables