A template setup for cpp project.

It contains the following:

• CMake as a build tool
• TravisCI for continuous integration
• Google Tests for testing the project libraries
• Google Benchmark for benchmarking the project libraries
• Documentation on readthedocs.org built using Sphinx, Doxygen and breathe.

The template documentation for this project is on readthedocs.

• CMake
• C 11
• Clang
• Linux (Xenial/Ubuntu 18.04)

As prequisites, CMAKE and git needs to be already installed.

cd graphs
sh install.sh

To generate documentation on readthedocs.org, do the following:

• On readthedocs.org, select your project for generating documentation and build.

cd docs
doxygen -g Doxyfile

Change the PROJECT_NAME in Doxyfile.

doxygen Doxyfile

Now let's do the sphinx part

sphinx-quickstart 

These are the prompts you get. We're going for a simple documentation setup here.

> Separate source and build directories (y/n) [n]: n
> Project name: python_project
> Author name(s): Wasim Akram Khan
> Project release []: 0.0.1
> Project language [en]: 

We have now setup the documentation

make html

To generate documentation locally each time you change the documentation:

cd docs
make clean
doxygen Doxyfile
make html

Open the docs/build/html/index.html in your browser to view the documentation on localhost.

cd docs
doxygen -g Doxyfile

Now change some things in the Doxyfile that you have just generated.

• PROJECT_NAME = "python_project"
• GENERATE_HTML = NO # (We don't need html output for readthedocs style docs)
• GENERATE_LATEX = NO

doxygen Doxyfile
sphinx-quickstart

Then you'll get some prompts.

> Separate source and build directories (y/n) [n]: y
> Project name: python_project
> Author name(s): Wasim Akram Khan
> Project release []: 0.0.1
> Project language [en]: 

You can see there are four files insides docs/source generated by sphinx: _static, _templates, conf.py, index.rst

The conf.py file defines how your source files are documented. You need to add the path of your package so that its files are reachable from conf.py.

Path of my conf.py: docs/source/conf.py

Add these two statements so conf.py can access your package.

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
sys.path.insert(0, os.path.abspath('../..'))

Extension tell doc generator what kind of stuffs to document and what not. For instance, sphinx.ext.viewcode provides link to the code code. Add the following to conf.py

# First two are essential to generate the docs, others are optional.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.ifconfig',
    'sphinx.ext.githubpages',
]

We're done with the configuration. See the source code for conf.py. I have done away with the boilerplate stuff and

docs/source/index.rst file is like the readme for the documentation. The changes you make to this file is seen in your documentation. In this file you define which python source file to document and which not to. You can include installation instructions, features, usage code snippets, etc in this file.

We built two libraries in this project: mathlib and strlib. We want both to be documented. So let's add that to the index.rst above "Indices and tables".

Math Lib
========
.. automodule:: python_project.mathlib
   :members:

String Lib
==========
.. automodule:: python_project.strlib
   :members:

View the source code for index.rst. I have done away with the boilerplate stuff and made the documentation more custom.

make html

We have now setup the documentation. Open the docs/build/html/index.html in your browser to view the documentation on localhost.

You can do this by testing different values for sys.path.insert()

To re-generate documentation locally each time you change the documentation:

cd docs
make clean
doxygen Doxyfile
make html

Open the docs/build/html/index.html in your browser to view the documentation on localhost.