projectm
projectm copied to clipboard
[WEBSITE] Add a project GitHub page with extensive Sphinx-generated documentation
Currently, libprojectM is documented in many different places: some Markdown files in the source code, the GitHub Wiki page and missing a generated Doxygen API documentation.
To keep the docs in one place and have them matching the current state of the code, we should add a docs dir in the library repo, with ReStructuredText (RST) files documenting all required parts:
- Introduction
- Getting the sources
- Building the sources
- Integrating the library in other projects
- Full API reference
- Contributing, community guidelines
- FAQ and other things worth mentioning
Using Sphinx to generate and deploy the docs via GitHub Actions will keep the docs up to date all the time, and users can find it in a single place.
What needs to be done?
- Create a new Sphinx project in a
docssubdirectory of the projectm repository. - Convert existing Markdown files from the repository and the wiki to RST.
- Create a GitHub page for the repository. Note: Must be done by a project maintainer!
- Add a GitHub Actions workflow to build and deploy the docs on every new push/merge/commit to master.
- Generate Doxygen API docs as XML and convert them to RST using doxyrest for example, include it in the Sphinx project.
- Remove/consolidate the existing stuff and point to the new page.
Looking around at the best way to bridge doxygen to sphinx, I'm seeing a lot of references to breathe, which is available from pypi and is also included in at least Ubuntu package repositories, whereas doxyrest does not appear to be. Is doxyrest a requirement or just one option for converting Doxygen output to something sphinx can import?