Initial import of sphinx project

[dpw13]

• Creates docs folder
• Converts top-level markdown files to RST in docs folder
• Adds doxygen, sphinx, and breathe options to CMakeLists.txt to generate projectm_sphinx build target
• Tweaks some of the generated RST to properly produce ToC and conform to sphinx's expectations

[dpw13]

This is less of a PR and more of an RFC. I didn't have opinions on the look and feel of the generated documentation; this PR only creates the scaffolding to produce somewhat sensical documentation as described in #731.

Generated documentation attached. Note that there are issues in generating the ToC; the index file has the ToC replicated in its body and I haven't figured out how to fix that.
projectm_sphinx.zip

[dpw13]

Turns out the tool exhale is really useful for organizing projects any larger than "trivial". New (much larger) generated docs attached.

projectm_sphinx.zip

[kblaschke]

Turns out the tool exhale is really useful for organizing projects any larger than "trivial". New (much larger) generated docs attached.

They use an interesting naming scheme in Sphinx. I actually like it 😆

[kblaschke]

This is the Sphinx project for the internal classes, right?

We also need another section in the docs for the public-facing API, which is the main area of interest for users of the library. This documentation needs to be generated from the installed files/headers only, so it doesn't include all the internal classes and also includes the proper (generated) files/directory structure of the final include directory.

Since some headers/code files are also generated during the source build, it'd be nice to include the additional include dirs in the build directory in the Sphinx project. Not sure how it'll deal with the directory structure though, as it could get messy. We probably have to create a temporary amalgamated "source" dir with all libprojectM headers, including the generated ones, in the build dir and then run Doxygen on this.

This is actually a point where Doxygen shows its age, it was definitely not designed for dynamic build systems which generate files out-of-source. It's always a pain to make it do what it needs to.

Oh, this is just a rant on ideas - the initial check-in is fine, way better than nothing and we can work through all the remaining things step by step of course :)

[kblaschke]

Is there an automated way of converting the Markdown files to RST?
If so, I'd actually prefer to do this when building the docs so the RST file is always the same as the respective top-level file, and we won't have to change them twice all the time - duplicated content is always a guarantee that it'll diverge over time.

[dpw13]

Yes, I used pandoc to do it, but I wasn't sure it made sense to add that as a dependency for building docs. In addition, it seemed like the conversion wasn't perfect and needed a bit of tweaking. The markdown may be able to be tweaked instead to make it work.

Would it make sense to replace the markdown with the RST version entirely, deleting the MD files (apart from simple READMEs) to avoid duplication?

[kblaschke]

RST is already quite popular these days and GitHub supports it, so personally I'm fine with it, especially given the fact reStructuredText is better suited for actual technical documentation than Markdown.

Once we have the documentation in place, we probably won't really need the building* files in the root dir anymore, so the docs and the main readme could just be separate things. Users could still just open the .rst files in the docs dir to read them, if someone is too lazy to visit the rendered page 😆

Let's just keep the files there so we have some content, and replace them one by one later on. We're really not in a rush there, projectM hasn't had proper documentation for a quarter of a century now, so a few weeks won't make much of a difference.