docs: improvements to source code documentation (#1236)

docs/Doxyfile

@@ -878,6 +878,7 @@ WARN_IF_UNDOC_ENUM_VAL = NO
 # The default value is: NO.
 
 WARN_AS_ERROR          = NO
+# todo - ideally this will eventually become FAIL_ON_WARNINGS
 
 # The WARN_FORMAT tag determines the format of the warning messages that doxygen
 # can produce. The string should contain the $file, $line, and $text tags, which
@@ -2354,7 +2355,7 @@ SEARCH_INCLUDES        = YES
 # RECURSIVE has no effect here.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
-INCLUDE_PATH           =
+INCLUDE_PATH           = ../third-party/ffmpeg-linux-x86_64/include/
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the

docs/source/conf.py

@@ -95,8 +95,16 @@ breathe_projects = dict(
 )
 todo_include_todos = True
 
-subprocess.run('doxygen', shell=True, cwd=source_dir)
-
 # disable epub mimetype warnings
 # https://github.com/readthedocs/readthedocs.org/blob/eadf6ac6dc6abc760a91e1cb147cc3c5f37d1ea8/docs/conf.py#L235-L236
 suppress_warnings = ["epub.unknown_project_files"]
+
+# get doxygen version
+doxy_proc = subprocess.run('doxygen --version', shell=True, cwd=source_dir, capture_output=True)
+doxy_version = doxy_proc.stdout.decode('utf-8').strip()
+print('doxygen version: ' + doxy_version)
+
+# run doxygen
+doxy_proc = subprocess.run('doxygen Doxyfile', shell=True, cwd=source_dir)
+if doxy_proc.returncode != 0:
+    raise RuntimeError('doxygen failed with return code ' + str(doxy_proc.returncode))