.. include:: ../global.rst

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:

.. code-block:: cpp

   #include <iostream>

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

You can insert the file with::

   .. literalinclude::
      :language: cpp

like this:

.. literalinclude:: hello.cpp
   :language: cpp

You can add to this:

.. csv-table:: literalinclude inclusion options
   :file: ../data/literalinclude.csv
   :header-rows: 1
   :widths: auto


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:

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

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.