C++ Intro

We will be keeping and documenting our projects in our Sphinx sites.

You cannot include sphinx directives in your C++ code. However, Sphinx does have directives to work with C++ at https://www.sphinx-doc.org/en/master/usage/domains/cpp.html.

You can show can also use:

.. code-block:: cpp

to include code such as:

#include <iostream>

int main() {
   std::cout << "Hello, World!" << std::endl;
   return 0;
}

You can insert the file with:

.. literalinclude::
   :language: cpp

like this:

#include <iostream>

int main() {
   // SPHINX: std example start
   std::cout << "Hello, World!" << std::endl;
   // SPHINX: std example end
   return 0;
}

You can add to this:

For example, you can get just part of the code like this:

.. literalinclude:: hello.cpp
   :language: cpp
   :start-after: // SPHINX: std example start
   :end-before: // SPHINX: std example end

Which gives this:

   std::cout << "Hello, World!" << std::endl;

Our Method

We are going to do most of our documenting in our C++ code using the standard method.

We will explain specifics in Sphinx when we need things like pictures or indexing.

Future Consideration

Note

C++ relies on preprocessors to work.

If someone would like to write a preprocessor to remove the Sphinx so we can compile the code, let us know.

If we go with a preprocessor, we can use a simple sentinel method rather than trying to determine what is C++ and what is Sphinx. For example:

.. comment start sphinx

.. image:: ../images/exclamation.svg
   :alt: exclamation graphic


.. comment end sphinx

When rendering this in sphinx the image will show up in the middle of the code.

The naming convention will be program_name.cpp.rst and the preprocessor will remove the sentinels and everything between them producing program_name.cpp which can be compiled.

Hence, our folders will often have program_name.cpp.rst and program_name.cpp. If we do this, it will be best to do our editing in the .rst file.