Build documentation with Sphinx and Doxygen and deploy to GitHub Pages

[wkearn]

This PR creates some user-facing documentation (#28) and a structured API reference (#27) using Doxygen, Sphinx and a few Sphinx plugins. The documentation can be built locally using a special CMake target (cmake --build build --target docs), assuming Doxygen, sphinx and the python packages breathe, myst-parser and sphinx-book-theme are installed -- at some point we should probably document the documentation and its build process a lot more thoroughly.

The content of the documentation currently includes a landing page adapted from the README of this repository, the Contribution Guidelines added in #38 and the structured API documentation that is automatically generated by Doxygen. All of the automatically generated documentation comes from formatted comments in include/topotoolbox.h, which represents the public API that can be accessed by external users. The function implementations and other internal functions (e.g. morphology/reconstruct.c) are not included in this documentation to make things as simple as possible. Contributors to libtopotoolbox therefore may still need to consult the comments in those implementations for additional documentation.

There is also a new GitHub Actions workflow that builds the documentation and deploys it to GitHub Pages.

This documentation is visible for review at https://wkearn.github.io/libtopotoolbox. Once this PR is merged, I will set up the GitHub Pages for this repository so that it will be found at https://topotoolbox.github.io/libtopotoolbox.

There are obviously a lot of choices to be made regarding documentation style, design, etc., and there is plenty more material that can be added to this documentation. For now, though I would like to get this framework set up so we at least have a place to start from with those decisions. @Teschl and @wschwanghart would you let me know what you think about the current version at https://wkearn.github.io/libtopotoolbox?

[Teschl]

The page looks great! It feels very familiar compared to the pandas or seaborn documentation (they also use Sphinx).

How are new pages/chapters added? I would like to get started on creating a basic guide/tutorial for getting started with the python TopoToolbox. In conjunction with resolving TopoToolbox/pytopotoolbox#18 . Also adding the documentation from the doc strings.

[wkearn]

How are new pages/chapters added?

The short answer is: you add a reStructuredText or Markdown file to the docs/ folder, then you add its name to the toctree section in docs/index.rst to get it to show up in the table of contents on the left side the main documentation page.

However, the way I have it set up now is that libtopotoolbox publishes its documentation to its own GitHub pages site at https://topotoolbox.github.io/libtopotoolbox. Our main webpage (https://topotoolbox.github.io) is published from the TopoToolbox/topotoolbox.github.io repository. Because GitHub Pages serves these from the same domain, it provides the illusion that they are the same website, but they are separate code bases.

If we proceed like this, we would probably set up the Python documentation within the pytopotoolbox repository, and it will end up at https://topotoolbox.github.io/pytopotoolbox.

I think the different sites would only be able to point to each other through absolute links in the HTML that Sphinx generates. For example, I don't think we would be able to display the full tables of contents for the C and Python documentation on the main page. We would have to link from the main page to each of them. If we generate all the documentation with Sphinx, we can share a theme (I'm using this one here) so that they all look similar.

My idea at the moment is that the individual repositories mostly hold automatically generated API references, documentation that is language-specific, and internal, developer-oriented documentation for that language. The main topotoolbox.github.io repository would then hold all of our shared documentation: tutorials, more science-focused descriptions of algorithms and analyses, etc. None of which would be automatically generated from the code.

The downside is that we have to make sure everything is linked properly and consistent across the different repositories. An alternative would be to host all of the documentation in topotoolbox.github.io and then do some more complicated build steps in that repository so that we have access to the sources needed for each package.