docs: use doxygen directly and drop breathe (#2739)
This commit is contained in:
ReenigneArcher
GitHub
parent
4683bcaf36
commit
10666c0194
50 changed files with 88 additions and 268 deletions
|
|
@ -8,6 +8,51 @@
|
|||
from datetime import datetime
|
||||
import os
|
||||
import subprocess
|
||||
from typing import Mapping, Optional
|
||||
|
||||
|
||||
# re-usable functions
|
||||
def _run_subprocess(
|
||||
args_list: list,
|
||||
cwd: Optional[str] = None,
|
||||
env: Optional[Mapping] = None,
|
||||
) -> bool:
|
||||
og_dir = os.getcwd()
|
||||
if cwd:
|
||||
os.chdir(cwd)
|
||||
process = subprocess.Popen(
|
||||
args=args_list,
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.STDOUT,
|
||||
cwd=cwd,
|
||||
encoding='utf-8',
|
||||
env=env,
|
||||
errors='replace',
|
||||
)
|
||||
|
||||
if cwd:
|
||||
os.chdir(og_dir)
|
||||
|
||||
# Print stdout and stderr in real-time
|
||||
# https://stackoverflow.com/a/57970619/11214013
|
||||
while True:
|
||||
realtime_output = process.stdout.readline()
|
||||
|
||||
if realtime_output == '' and process.poll() is not None:
|
||||
break
|
||||
|
||||
if realtime_output:
|
||||
print(realtime_output.strip(), flush=True)
|
||||
|
||||
process.stdout.close()
|
||||
|
||||
exit_code = process.wait()
|
||||
|
||||
if exit_code != 0:
|
||||
print(f'::error:: Process [{args_list}] failed with exit code', exit_code)
|
||||
raise RuntimeError(f'Process [{args_list}] failed with exit code {exit_code}')
|
||||
else:
|
||||
return True
|
||||
|
||||
|
||||
# -- Path setup --------------------------------------------------------------
|
||||
|
|
@ -35,11 +80,9 @@ version = os.getenv('READTHEDOCS_VERSION', 'dirty')
|
|||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
'breathe', # c++ support for sphinx with doxygen
|
||||
'm2r2', # enable markdown files
|
||||
'sphinx.ext.autosectionlabel',
|
||||
'sphinx.ext.todo', # enable to-do sections
|
||||
'sphinx.ext.graphviz', # enable graphs for breathe
|
||||
'sphinx.ext.viewcode', # add links to view source code
|
||||
'sphinx_copybutton', # add a copy button to code blocks
|
||||
'sphinx_inline_tabs', # add tabs
|
||||
|
|
@ -79,12 +122,6 @@ html_theme_options = {
|
|||
|
||||
# extension config options
|
||||
autosectionlabel_prefix_document = True # Make sure the target is unique
|
||||
breathe_default_project = 'src'
|
||||
breathe_implementation_filename_extensions = ['.c', '.cc', '.cpp', '.mm']
|
||||
breathe_order_parameters_first = False
|
||||
breathe_projects = dict(
|
||||
src="../build/doxyxml"
|
||||
)
|
||||
todo_include_todos = True
|
||||
|
||||
# disable epub mimetype warnings
|
||||
|
|
@ -92,14 +129,15 @@ todo_include_todos = True
|
|||
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)
|
||||
doxy_version = _run_subprocess(
|
||||
args_list=['doxygen', '--version'],
|
||||
cwd=source_dir,
|
||||
)
|
||||
|
||||
# create build directories, as doxygen fails to create it in macports and docker
|
||||
directories = [
|
||||
os.path.join(source_dir, 'build'),
|
||||
os.path.join(source_dir, 'build', 'doxyxml'),
|
||||
os.path.join(source_dir, 'build', 'doxygen', 'doxyhtml'),
|
||||
]
|
||||
for d in directories:
|
||||
os.makedirs(
|
||||
|
|
@ -108,6 +146,12 @@ for d in directories:
|
|||
)
|
||||
|
||||
# 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))
|
||||
doxy_proc = _run_subprocess(
|
||||
args_list=['doxygen', 'Doxyfile'],
|
||||
cwd=source_dir
|
||||
)
|
||||
|
||||
# copy doxygen html files
|
||||
html_extra_path = [
|
||||
os.path.join(source_dir, 'build', 'doxygen'), # the final directory is omitted in order to have a proper path
|
||||
]
|
||||
|
|
|
|||
|
|
@ -55,37 +55,12 @@ Example Documentation Blocks
|
|||
Source
|
||||
------
|
||||
|
||||
.. toctree::
|
||||
:caption: src
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
Please refer to the `Doxygen Documentation <../doxyhtml/index.html>`_ for more details.
|
||||
|
||||
src/*
|
||||
.. todo:: Sphinx and Breathe do not support the Objective-C Domain.
|
||||
See https://github.com/breathe-doc/breathe/issues/129
|
||||
|
||||
.. toctree::
|
||||
:caption: src/platform
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
.. .. doxygenindex::
|
||||
.. :allow-dot-graphs:
|
||||
|
||||
src/platform/*
|
||||
|
||||
.. toctree::
|
||||
:caption: src/platform/linux
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
src/platform/linux/*
|
||||
|
||||
.. toctree::
|
||||
:caption: src/platform/macos
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
src/platform/macos/*
|
||||
|
||||
.. toctree::
|
||||
:caption: src/platform/windows
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
src/platform/windows/*
|
||||
.. Ideally, we would use `doxygenfile` with `:allow-dot-graphs:`, but sphinx complains about duplicated namespaces...
|
||||
|
|
|
|||
|
|
@ -1,5 +0,0 @@
|
|||
audio
|
||||
=====
|
||||
|
||||
.. doxygenfile:: audio.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
cbs
|
||||
===
|
||||
|
||||
.. doxygenfile:: cbs.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
config
|
||||
======
|
||||
|
||||
.. doxygenfile:: config.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
confighttp
|
||||
==========
|
||||
|
||||
.. doxygenfile:: confighttp.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
crypto
|
||||
======
|
||||
|
||||
.. doxygenfile:: crypto.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
entry_handler
|
||||
=============
|
||||
|
||||
.. doxygenfile:: entry_handler.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
file_handler
|
||||
============
|
||||
|
||||
.. doxygenfile:: file_handler.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
globals
|
||||
=======
|
||||
|
||||
.. doxygenfile:: globals.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
httpcommon
|
||||
==========
|
||||
|
||||
.. doxygenfile:: httpcommon.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
input
|
||||
=====
|
||||
|
||||
.. doxygenfile:: input.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
logging
|
||||
=======
|
||||
|
||||
.. doxygenfile:: logging.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
main
|
||||
====
|
||||
|
||||
.. doxygenfile:: main.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
move_by_copy
|
||||
============
|
||||
|
||||
.. doxygenfile:: move_by_copy.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
network
|
||||
=======
|
||||
|
||||
.. doxygenfile:: network.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
nvhttp
|
||||
======
|
||||
|
||||
.. doxygenfile:: nvhttp.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
common
|
||||
======
|
||||
|
||||
.. todo:: Add common.h
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
cuda
|
||||
====
|
||||
|
||||
.. doxygenfile:: platform/linux/cuda.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
graphics
|
||||
========
|
||||
|
||||
.. todo:: Add graphics.h
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
misc
|
||||
====
|
||||
|
||||
.. todo:: Add misc.h
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
vaapi
|
||||
=====
|
||||
|
||||
.. doxygenfile:: platform/linux/vaapi.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
wayland
|
||||
=======
|
||||
|
||||
.. doxygenfile:: platform/linux/wayland.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
x11grab
|
||||
=======
|
||||
|
||||
.. todo:: Add x11grab.h
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
av_audio
|
||||
========
|
||||
|
||||
.. todo:: Add av_audio.h
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
av_img_t
|
||||
========
|
||||
|
||||
.. todo:: Add av_img_t.h
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
av_video
|
||||
========
|
||||
|
||||
.. todo:: Add av_video.h
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
misc
|
||||
====
|
||||
|
||||
.. doxygenfile:: platform/macos/misc.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
nv12_zero_device
|
||||
================
|
||||
|
||||
.. todo:: Add nv12_zero_device.h
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
PolicyConfig
|
||||
============
|
||||
|
||||
.. todo:: Add PolicyConfig.h
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
display
|
||||
=======
|
||||
|
||||
.. todo:: Add display.h
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
misc
|
||||
====
|
||||
|
||||
.. doxygenfile:: platform/windows/misc.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
process
|
||||
=======
|
||||
|
||||
.. doxygenfile:: process.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
round_robin
|
||||
===========
|
||||
|
||||
.. doxygenfile:: round_robin.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
rtsp
|
||||
====
|
||||
|
||||
.. doxygenfile:: rtsp.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
stream
|
||||
======
|
||||
|
||||
.. doxygenfile:: stream.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
sync
|
||||
====
|
||||
|
||||
.. doxygenfile:: sync.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
system_tray
|
||||
===========
|
||||
|
||||
.. doxygenfile:: system_tray.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
task_pool
|
||||
=========
|
||||
|
||||
.. doxygenfile:: task_pool.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
thread_pool
|
||||
===========
|
||||
|
||||
.. doxygenfile:: thread_pool.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
thread_safe
|
||||
===========
|
||||
|
||||
.. doxygenfile:: thread_safe.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
upnp
|
||||
====
|
||||
|
||||
.. doxygenfile:: upnp.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
utility
|
||||
=======
|
||||
|
||||
.. todo:: Add utility.h
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
uuid
|
||||
====
|
||||
|
||||
.. doxygenfile:: uuid.h
|
||||
:allow-dot-graphs:
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
video
|
||||
=====
|
||||
|
||||
.. doxygenfile:: video.h
|
||||
:allow-dot-graphs:
|
||||
Loading…
Add table
Add a link
Reference in a new issue