OpenShot / libopenshot-audio

OpenShot Audio Library (libopenshot-audio) is a free, open-source project that enables high-quality editing and playback of audio, and is based on the amazing JUCE library.
http://www.openshot.org
GNU General Public License v3.0
254 stars 101 forks source link

Docs: Switch from UseDoxygen to doxygen_add_docs #111

Closed ferdnyc closed 3 years ago

ferdnyc commented 3 years ago

Since CMake 3.11, the supported method of integrating Doxygen into CMake projects has been via the doxygen_add_docs() CMake function, which (crucially) can be passed a target name to create and doesn't rely on tons of hardcoding like our UseDoxygen.cmake and its Doxyfile.in template did.

This means our docs (only) now require CMake 3.11 to generate, but it allows Doxygen to be configured/used multiple times in the same CMake configuration, removing a major barrier to superproject builds.

Also, made docs disableable via an ENABLE_AUDIO_DOCS option, and adopt FeatureSummary into the build.

Because the JUCE Doxygen setup is... complex, they had been pre-processing the source to get a certain documentation hierarchy, something we used to be sort-of approximating badly. That's now done away with, so the docs don't generate exactly like they previously did. But, it's actually better now (IMHO) and still plenty usable. I think the improvements are worth the disruption.

ferdnyc commented 3 years ago

Significant changes: I decided that preprocessing the source files wasn't really improving the docs; JUCE did it (according to comments in the Python script) for two main reasons:

  1. To keep the doc URLs the same as they were before, after they added namespaces — something we don't care about
  2. To add module-level documentation and grouping to the docs — something we don't need to bother with, because we've already selected the included modules, so the user doesn't have any control over modules or need to know about modules

This also means building the docs no longer requires Python.

jonoomph commented 3 years ago

LGTM