****** Sphinx ****** `Sphinx `_ is a documentation tool that is commonly used for writing code documentation (especially for python projects). It uses `restructured text `_ 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 #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 (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.