******
Sphinx
******

`Sphinx <https://www.sphinx-doc.org/en/master/>`_ is a documentation
tool that is commonly used for writing code documentation (especially
for python projects).  It uses `restructured text
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
as the format for writing the documentation and compiles it into HTML,
LaTeX/PDF, ...  It can also highlight code syntax.

.. tip::

   These course notes are all written using Sphinx


Setting It Up
=============

We can install Sphinx locally via:

.. prompt:: bash

   pip3 install sphinx sphinx_rtd_theme breathe --user

.. tip::

   On the MathLab machines, python 2 is the default, which is why we are
   using ``pip3`` here, to ensure that we get python 3.

.. tip::

   For some reason, the MathLab machines don't include
   ``~/.local/bin`` in your Unix path, so we need to manually add it via:

   .. prompt:: bash

      export PATH=~/.local/bin:$PATH

Now we want to change our code documentation from our handwritten
``index.html`` to a site generated by Sphinx.  We'll take over the
``docs/`` directory:

.. prompt:: bash

   cd docs/
   rm index.html

Then, in the ``docs/`` directory:

.. prompt:: bash

   sphinx-quickstart

Answer the following:

* ``Separate source and build directories (y/n) [n]:`` : answer ``y``

* ``Project name:`` : answer "C++ Array"

* ``Author names(s):`` : answer "PHY 504"

* ``Project release []:`` : just hit enter

* ``Project language [en]:`` : just hit enter

You should now have the following files:

::

    build/
    make.bat
    Makefile
    source/

you can delete ``make.bat``.

To test things out, do:

.. prompt:: bash

   make html

Then you can view the default page via:

.. prompt:: bash

   google-chrome build/html/index.html


Customizing our page
====================

There are two important files in ``source/``

* ``conf.py`` : this controls the configuration of Sphinx

* ``index.rst`` : this is the ReST file that will become ``index.html``.

Configuration
-------------

Let's start by changing the configuration a bit:

* in the ``extensions`` section, change it to read:

  .. code:: python

     extensions = ["breathe"]

* change ``html_theme`` to be:

  .. code:: python

     html_theme = "sphinx_rtd_theme"


Index
-----

Let's have the ``index.rst`` page link to a page showing how the library works.

Create a file ``using.rst`` with the following content:

.. code:: ReST

   ***********
   Using Array
   ***********

   ``Array.H`` provides a simple 2-d contiguous array.  We can use it as:

   .. code:: c++

      #include <iostream>

      #include "array.H"

      int main() {

          // create a 10x10 array

          Array x(10, 10);

          for (std::size_t row=0; row < x.nrows(); ++row) {
              for (std::size_t col=0; col < x.ncols(); ++col) {
                  x(row, col) = static_cast<double> (10*row + 100*col + 13);
              }
          }

          std::cout << x << std::endl;

          std::cout << "x.min() = " << x.min() << std::endl;

          // create a 4x3 array but fill it by looping over a flattened
          // view

          Array y(4, 3);

          double c{0};
          for (auto &e : y.flat()) {
              e = c;
              c += 1;
          }

          std::cout << y << std::endl;




Then add to ``index.rst`` just after the contents ``using``, so it reads like:

.. code:: ReST

   .. toctree::
      :maxdepth: 2
      :caption: Contents:

      using

Let's add what we've do so far to our git:

.. prompt:: bash

   git add Makefile source/conf.py source/index.rst source/using.rst
   git commit

We now need to change our GitHub action to build this new site and
copy it over to the ``gh-pages`` branch.

In the ``.github/workflows/gh-pages.yml`` file, change the sections:

.. code:: yaml

   - name: Build Doxygen
     run: |
          mkdir docs
          doxygen Doxyfile

   - name: Deploy
     uses: peaceiris/actions-gh-pages@v4
     with:
       github_token: ${{ secrets.GITHUB_TOKEN }}
       publish_dir: ./docs
       keep_files: true

to

.. code:: yaml

   - name: Build Sphinx
     run: |
          cd docs
          make html
          cd ..
          mkdir -p out
          mv docs/build/html/* out/

   - name: Deploy
     uses: peaceiris/actions-gh-pages@v4
     with:
       github_token: ${{ secrets.GITHUB_TOKEN }}
       publish_dir: ./out
       keep_files: true

This does 3 things:

* It switches to building the sphinx pages via ``make html``

* It creates a top-level directory called ``out/`` and puts all of the web site there

* It instructs the "Deploy" process to copy ``out`` to ``gh-pages`` now

.. tip::

   Commit and push these changes and in a minute or two, the project webpage should
   be regenerated to reflect the Sphinx layout.