******* Doxygen ******* `Doxygen `_ is a standard tool for documenting C++ code. It works off of comments added to the code to build documentation (including web pages) describing the structure of a code and its classes and functions. We'll continue to work on our ``cxx-array`` repo that we just created. But to help automate things, we need to make a change to how the webpage is stored. Using ``gh-pages`` ================== Our goal is to have GitHub automatically generate our website. When we do this, it is best to have the actual web page on a separate branch so we don't have to keep merging with the regenerating web page every time we make changes. This is the purpose of the ``gh-pages`` branch. It is an *orphaned branch*, so it doesn't have any connection to ``main``. Creating the ``gh-pages`` branch -------------------------------- We'll follow `these instructions `_ for creating the ``gh-pages`` branch. Here's the procedure. In ``cxx-array/``, make sure you don't have any uncommitted work, and then do: .. prompt:: bash git checkout --orphan gh-pages git reset --hard git commit --allow-empty -m "Initializing gh-pages branch" Now add an ``index.html`` in the empty directory: .. code:: html Hello

C++ Array Class

Array.H provides a simple C++ multi-dimensional array class.

Let's also add the ``.nojekyll`` file: .. prompt:: bash touch .nojekyll Now let's commit these: .. prompt:: bash git add index.html .nojekyll git commit Finally, let's push our branch to our repo: .. prompt:: bash git push origin gh-pages Updating the web location on GitHub ----------------------------------- Now we need to go back to the GitHub page for our repo and go to settings and "Pages" and change the "Source" to be "Branch: gh-pages" and "/ (root)" and save. After a minute or so, the page should be regenerated and appear at the same URL as before. .. note:: From now on, when we want to manually make changes to our web page, we need to be on the ``gh-pages`` branch. We can now switch back to ``main``: .. prompt:: bash git checkout main Setting permissions ------------------- We also need to update our github repo to grant an action the ability to write to our repo. Under the *settings* menu, go to *actions* settings in the left pane (and pick *general*). Then navigate to the "workflow permissions" section near the bottom and grant read/write permissions like shown below: .. image:: github-permissions.png Doxygen configuration ===================== Setting up: https://www.doxygen.nl/manual/starting.html .. prompt:: bash doxygen -g This creates a file called ``Doxyfile``. We need to make a few edits to it: * We want to change ``PROJECT_NAME`` to ``C++ Array`` * We want to change ``OUTPUT_DIRECTORY`` to ``docs``, since that's where we expect our source to live * We'll have Doxygen use the same ``README.md`` that github displays as the main page for the Doxygen start page. This is done by changing: .. code:: USE_MDFILE_AS_MAINPAGE = README.md * We'll turn off Latex output by changing ``GENERATE_LATEX`` from ``YES`` to ``NO`` * We've been using ``*.H`` for our header files, so we need to add this to the list ``FILE_PATTERNS`` in the ``Doxyfile``. Doxygen already associates ``.H`` with C++, but just doesn't search for it by default. .. tip:: Add ``Doxyfile`` to your git repo and commit. Annotating our code =================== Doxygen uses ``///`` as the `documentation comment style `_ for C++. So we would do: .. code:: c++ /// /// a function to add two numbers /// double add(double x, double y); Note that we have an empty ``///`` before and after the documentation. Now we can annotate our C++ ``Array`` class code. Here's a version of ``array.H`` that we developed in class with some documentation comments. .. literalinclude:: ../../examples/doxygen/array.H :language: c++ :caption: ``array.H`` .. tip:: Add ``array.H`` to your git repo and commit. Trying it out locally --------------------- We can test out Doxygen locally by doing: .. prompt:: bash doxygen Doxyfile The HTML will then be in the ``docs/html/`` directory, and we can view the page as: .. prompt:: bash google-chrome docs/html/index.html .. tip:: The default Doxygen generated pages look a little bland. There are `themes available `_ to make it look a lot nicer. Setting up a GitHub action ========================== Now create a file: ``.github/workflows/gh-pages.yml`` with the following content: .. code:: yaml name: github pages on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install pandoc and doxygen run: | sudo apt install pandoc doxygen - name: Setup python uses: actions/setup-python@v5 with: python-version: '3.12' - name: Install dependencies run: python3 -m pip install -r ./requirements.txt - name: Build Doxygen run: | mkdir -p docs doxygen Doxyfile - name: Deploy uses: peaceiris/actions-gh-pages@v4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs keep_files: true This does a little more than we need for now, as it gets us prepped for Sphinx coming next. Since we're adding stuff, let's add a ``cxx-array/requirements.txt`` now as well, with the following content: .. code:: sphinx sphinx_rtd_theme breathe .. tip:: Add ``requirements.txt`` and ``.github/workflow/gh-pages.yml`` to your git repo and commit. One last thing... ================= We need to go back to ``gh-pages`` and now link to the Doxygen docs from our ``index.html``. We can do that with the following addition to ``index.html``: .. code:: html Doxygen documentation Finally, ``git push`` these changes back to GitHub. .. admonition:: voila! If everything worked correctly, then the GitHub action should run Doxygen and copy the HTML it generated to our web page.