mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2025-11-03 09:01:54 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions
pipewire/doc/meson.build

157 lines
4.6 KiB
Meson
Raw Normal View History

Add doxygen docs
2017-05-30 19:46:51 +02:00
doxyfile_conf = configuration_data()
doxyfile_conf.set('PACKAGE_NAME', meson.project_name())
doxyfile_conf.set('PACKAGE_VERSION', meson.project_version())
Revert "[Meson] Fix all deprecation warnings" This reverts commit f7e1175ef084cf74153b3e37cc92b1ee2f3e5e10.
2021-08-06 16:23:12 +02:00
doxyfile_conf.set('top_srcdir', meson.source_root())
doxyfile_conf.set('top_builddir', meson.build_root())
Add doxygen docs
2017-05-30 19:46:51 +02:00
meson.build: adds summary() to optional programs
2021-06-29 11:17:03 +03:00
dot_found = find_program('dot', required: false).found()
summary({'dot (used with doxygen)': dot_found}, bool_yn: true, section: 'Optional programs')
if dot_found
Add doxygen docs
2017-05-30 19:46:51 +02:00
doxyfile_conf.set('HAVE_DOT', 'YES')
else
doxyfile_conf.set('HAVE_DOT', 'NO')
endif
doc: switch from .md to .dox files and impose some general structure This is an attempt of breaking up the documentation, currently spread across several pages. We're left with a few high-level topics with various things grouped underneath those. Further refinement is necessary, but this can now be done in incremental steps over massive reworks.
2021-05-25 19:55:06 +10:00
# Note: order here is how doxygen will expose the pages in the sidebar
doc: reorganize Doxygen groups/modules to make more sense The Doxygen "Modules" page is not very illuminative, as different parts of the API are mixed together and not all parts are included. Try to address this: Put all parts of the public API to some Doxygen group, usually one group per header file. Use short, systematic names. Make these groups sub-groups of a few top-level groups, roughly corresponding to the different logical parts of the API (core, impl, stream, filter, spa, utilities).
2021-10-02 20:55:53 +03:00
# api-tree.dox should be first to determine ordering of Modules.
doc: add the various markdown prose docs to the doxygen output Note that the order of the includes matters - that's how doxygen will sort them. There is no specific structure other than the include order - one reason why the headers are being changed. Without polluting the markdown files with doxygen commands we cannot use \subpage, so all files convert to a regular \page and are listed as flat hierarchy in the sidebar (and in Related Pages). Changing the headers at least provides some visual grouping with comon prefixes.
2021-05-07 09:09:45 +10:00
extra_docs = [
doc: reorganize Doxygen groups/modules to make more sense The Doxygen "Modules" page is not very illuminative, as different parts of the API are mixed together and not all parts are included. Try to address this: Put all parts of the public API to some Doxygen group, usually one group per header file. Use short, systematic names. Make these groups sub-groups of a few top-level groups, roughly corresponding to the different logical parts of the API (core, impl, stream, filter, spa, utilities).
2021-10-02 20:55:53 +03:00
'api-tree.dox',
doc: switch from .md to .dox files and impose some general structure This is an attempt of breaking up the documentation, currently spread across several pages. We're left with a few high-level topics with various things grouped underneath those. Further refinement is necessary, but this can now be done in incremental steps over massive reworks.
2021-05-25 19:55:06 +10:00
'index.dox',
doc: move the overview page out to its own page This is a good first (top) page to have in the docs, let's move it out from the pipewire heading. This doesn't change any of the links and the renaming isn't required (subpage controls whether it's a top-level item and the meson.build order decides its spot in he list). Still, better to have the filenames represent the layout.
2021-07-29 14:29:46 +10:00
'overview.dox',
doc: switch from .md to .dox files and impose some general structure This is an attempt of breaking up the documentation, currently spread across several pages. We're left with a few high-level topics with various things grouped underneath those. Further refinement is necessary, but this can now be done in incremental steps over massive reworks.
2021-05-25 19:55:06 +10:00
'pipewire.dox',
'pipewire-design.dox',
doc: remove the Pipewire prefix from some of the doc pages
2021-07-29 14:25:47 +10:00
'pipewire-access.dox',
'pipewire-midi.dox',
'pipewire-portal.dox',
doc: switch from .md to .dox files and impose some general structure This is an attempt of breaking up the documentation, currently spread across several pages. We're left with a few high-level topics with various things grouped underneath those. Further refinement is necessary, but this can now be done in incremental steps over massive reworks.
2021-05-25 19:55:06 +10:00
'pipewire-daemon.dox',
'pipewire-library.dox',
doc: add the documentation infrastructure for pipewire modules All empty pages for now but at least this makes them show up in the documentation.
2021-06-24 14:06:30 +10:00
'pipewire-modules.dox',
doc: switch from .md to .dox files and impose some general structure This is an attempt of breaking up the documentation, currently spread across several pages. We're left with a few high-level topics with various things grouped underneath those. Further refinement is necessary, but this can now be done in incremental steps over massive reworks.
2021-05-25 19:55:06 +10:00
'pipewire-tools.dox',
'pipewire-session-manager.dox',
'pipewire-objects-design.dox',
doc: add the new documentation pages to the docs And make them a subpage of the Pipewire topic
2021-07-29 14:11:34 +10:00
'pipewire-audio.dox',
doc: add a media-session header file with the access-flatpak module This adds a new top-level documentation entry for pipewire-media-session with a list of modules (currently only one). Similar setup to the pipewire modules, it allows us to document all modules in-place.
2021-07-29 15:44:37 +10:00
'media-session.dox',
doc: change the tutorials to doxygen sources While doxygen can handle markdown pages, support for it is very limited: markdown pages can only be included as a whole page, they get an automatic title (custom titles are possible but aren't standard markdown) and it's not possible to use \subpage without messing with the markdown again. Any markdown page will thus end up as separate item in the doxygen output, not really suitable for generating a good page hiearchy. Let's switch the tutorial to use doxygen directly instead of markdown, short of using code/endcode instead of markdown's ``` there isn't that much difference anyway but it allows us to structure things nicer in the online docs.
2021-05-25 13:08:04 +10:00
'tutorial.dox',
'tutorial1.dox',
'tutorial2.dox',
'tutorial3.dox',
'tutorial4.dox',
'tutorial5.dox',
'tutorial6.dox',
doc: reorganize Doxygen groups/modules to make more sense The Doxygen "Modules" page is not very illuminative, as different parts of the API are mixed together and not all parts are included. Try to address this: Put all parts of the public API to some Doxygen group, usually one group per header file. Use short, systematic names. Make these groups sub-groups of a few top-level groups, roughly corresponding to the different logical parts of the API (core, impl, stream, filter, spa, utilities).
2021-10-02 20:55:53 +03:00
'api.dox',
doc: switch the spa documentation to doxygen
2021-05-25 13:37:47 +10:00
'spa-index.dox',
doc: rework the SPA plugin documentation Add more info to the main SPA page and split the design vs plugin pages up, together with some more documentation to ideally lower make this easier to understand on a glance. Most of the actual plugin loading documentation are unmodified.
2021-06-24 10:49:22 +10:00
'spa-plugins.dox',
doc: switch the spa documentation to doxygen
2021-05-25 13:37:47 +10:00
'spa-design.dox',
'spa-pod.dox',
'spa-buffer.dox',
doc: switch from .md to .dox files and impose some general structure This is an attempt of breaking up the documentation, currently spread across several pages. We're left with a few high-level topics with various things grouped underneath those. Further refinement is necessary, but this can now be done in incremental steps over massive reworks.
2021-05-25 19:55:06 +10:00
'pulseaudio.dox',
doc: add DMA-BUF docs
2021-07-29 15:25:06 +02:00
'dma-buf.dox',
doc: add the various markdown prose docs to the doxygen output Note that the order of the includes matters - that's how doxygen will sort them. There is no specific structure other than the include order - one reason why the headers are being changed. Without polluting the markdown files with doxygen commands we cannot use \subpage, so all files convert to a regular \page and are listed as flat hierarchy in the sidebar (and in Related Pages). Changing the headers at least provides some visual grouping with comon prefixes.
2021-05-07 09:09:45 +10:00
]
doc: reorganize Doxygen groups/modules to make more sense The Doxygen "Modules" page is not very illuminative, as different parts of the API are mixed together and not all parts are included. Try to address this: Put all parts of the public API to some Doxygen group, usually one group per header file. Use short, systematic names. Make these groups sub-groups of a few top-level groups, roughly corresponding to the different logical parts of the API (core, impl, stream, filter, spa, utilities).
2021-10-02 20:55:53 +03:00
inputs = []
doc: add the various markdown prose docs to the doxygen output Note that the order of the includes matters - that's how doxygen will sort them. There is no specific structure other than the include order - one reason why the headers are being changed. Without polluting the markdown files with doxygen commands we cannot use \subpage, so all files convert to a regular \page and are listed as flat hierarchy in the sidebar (and in Related Pages). Changing the headers at least provides some visual grouping with comon prefixes.
2021-05-07 09:09:45 +10:00
foreach extra : extra_docs
Revert "[Meson] Fix all deprecation warnings" This reverts commit f7e1175ef084cf74153b3e37cc92b1ee2f3e5e10.
2021-08-06 16:23:12 +02:00
inputs += meson.source_root() / 'doc' / extra
doc: add the various markdown prose docs to the doxygen output Note that the order of the includes matters - that's how doxygen will sort them. There is no specific structure other than the include order - one reason why the headers are being changed. Without polluting the markdown files with doxygen commands we cannot use \subpage, so all files convert to a regular \page and are listed as flat hierarchy in the sidebar (and in Related Pages). Changing the headers at least provides some visual grouping with comon prefixes.
2021-05-07 09:09:45 +10:00
endforeach
doc: reorganize Doxygen groups/modules to make more sense The Doxygen "Modules" page is not very illuminative, as different parts of the API are mixed together and not all parts are included. Try to address this: Put all parts of the public API to some Doxygen group, usually one group per header file. Use short, systematic names. Make these groups sub-groups of a few top-level groups, roughly corresponding to the different logical parts of the API (core, impl, stream, filter, spa, utilities).
2021-10-02 20:55:53 +03:00
foreach h : pipewire_headers
inputs += meson.source_root() / 'src' / 'pipewire' / h
endforeach
foreach h : pipewire_ext_headers
inputs += meson.source_root() / 'src' / 'pipewire' / 'extensions' / h
endforeach
foreach h : pipewire_ext_sm_headers
inputs += meson.source_root() / 'src' / 'pipewire' / 'extensions' / h
endforeach
foreach h : pipewire_sources
inputs += meson.source_root() / 'src' / 'pipewire' / h
endforeach
foreach h : module_sources
inputs += meson.source_root() / 'src' / 'modules' / h
endforeach
foreach h : media_session_sources
inputs += meson.source_root() / 'src' / 'media-session' / h
endforeach
inputs += meson.source_root() / 'test' / 'pwtest.h'
doc: fix meson dependency list Meson doesn't accept directories in input dependency list.
2021-10-04 22:14:38 +03:00
input_dirs = [ meson.source_root() / 'spa' / 'include' / 'spa' ]
doc: reorganize Doxygen groups/modules to make more sense The Doxygen "Modules" page is not very illuminative, as different parts of the API are mixed together and not all parts are included. Try to address this: Put all parts of the public API to some Doxygen group, usually one group per header file. Use short, systematic names. Make these groups sub-groups of a few top-level groups, roughly corresponding to the different logical parts of the API (core, impl, stream, filter, spa, utilities).
2021-10-02 20:55:53 +03:00
path_prefixes = [
meson.source_root() / 'src',
meson.source_root() / 'spa' / 'include',
meson.source_root(),
]
doc: add the various markdown prose docs to the doxygen output Note that the order of the includes matters - that's how doxygen will sort them. There is no specific structure other than the include order - one reason why the headers are being changed. Without polluting the markdown files with doxygen commands we cannot use \subpage, so all files convert to a regular \page and are listed as flat hierarchy in the sidebar (and in Related Pages). Changing the headers at least provides some visual grouping with comon prefixes.
2021-05-07 09:09:45 +10:00
doc: add a custom doxygen theme based on doxygen-awesome Theme from doxygen-awesome-css with custom modifications based on the pipewire.org website to use the same type of blue, grey, etc. doxygen-awesome-css is MIT licensed, see https://github.com/jothepro/doxygen-awesome-css
2021-05-21 14:53:48 +10:00
cssfiles = [
Revert "[Meson] Fix all deprecation warnings" This reverts commit f7e1175ef084cf74153b3e37cc92b1ee2f3e5e10.
2021-08-06 16:23:12 +02:00
meson.source_root() / 'doc' / 'doxygen-awesome.css',
meson.source_root() / 'doc' / 'custom.css'
doc: add a custom doxygen theme based on doxygen-awesome Theme from doxygen-awesome-css with custom modifications based on the pipewire.org website to use the same type of blue, grey, etc. doxygen-awesome-css is MIT licensed, see https://github.com/jothepro/doxygen-awesome-css
2021-05-21 14:53:48 +10:00
]
doc: link examples to Doxygen docs Include examples to the documentation, using Doxygen's example system.
2021-10-09 23:25:29 +03:00
# Example files (in order from simple to esoteric)
example_files = [
doc: add tutorials as Doxygen examples
2021-10-10 00:09:32 +03:00
'tutorial1.c',
'tutorial2.c',
'tutorial3.c',
'tutorial4.c',
'tutorial5.c',
'tutorial6.c',
doc: link examples to Doxygen docs Include examples to the documentation, using Doxygen's example system.
2021-10-09 23:25:29 +03:00
'audio-src.c',
'audio-dsp-src.c',
'audio-dsp-filter.c',
'video-play.c',
'video-src.c',
'video-dsp-play.c',
'video-play-pull.c',
'video-play-reneg.c',
'video-src-alloc.c',
'video-src-reneg.c',
'export-sink.c',
'export-source.c',
'export-spa.c',
'export-spa-device.c',
'bluez-session.c',
'local-v4l2.c',
'spa/examples/adapter-control.c',
'spa/examples/example-control.c',
'spa/examples/local-libcamera.c',
'spa/examples/local-v4l2.c',
]
example_doxygen = []
example_ref = []
foreach h : example_files
example_doxygen += ['\\example ' + h,
'\\snippet{doc} ' + h + ' title',
'<br>',
'\\snippet{doc} ' + h + ' doc']
example_ref += ['- \\ref ' + h + ' "": \snippet{doc} ' + h + ' title']
endforeach
examples_dox_conf = configuration_data()
examples_dox_conf.set('example_doxygen', '\n'.join(example_doxygen))
examples_dox_conf.set('example_ref', '\n'.join(example_ref))
examples_dox = configure_file(input: 'examples.dox.in',
output: 'examples.dox',
configuration: examples_dox_conf)
input_dirs += [ 'doc/examples.dox' ]
doc: fix meson dependency list Meson doesn't accept directories in input dependency list.
2021-10-04 22:14:38 +03:00
doxyfile_conf.set('inputs', ' '.join(inputs + input_dirs))
doc: add a custom doxygen theme based on doxygen-awesome Theme from doxygen-awesome-css with custom modifications based on the pipewire.org website to use the same type of blue, grey, etc. doxygen-awesome-css is MIT licensed, see https://github.com/jothepro/doxygen-awesome-css
2021-05-21 14:53:48 +10:00
doxyfile_conf.set('cssfiles', ' '.join(cssfiles))
doc: make Doxygen to show only symbols defined in headers Make Doxygen data structure etc. lists less cluttered by hiding non-public stuff. Add a Doxygen input filter that marks symbols declared in C files private, so that they won't appear in the output unless the symbol is also declared in a header. The "spa static inline" hack is then also not needed any more.
2021-10-02 19:24:17 +03:00
doxyfile_conf.set('path_prefixes', ' '.join(path_prefixes))
doxyfile_conf.set('c_input_filter', meson.source_root() / 'doc' / 'input-filter.sh')
doc: add Doxygen filter that adds docs to struct *method macros Add an input filter that tries to link e.g. #define pw_core_add_listener(...) pw_core_method(c,add_listener,...) to the corresponding declaration in struct pw_core_methods.
2021-10-02 22:22:59 +03:00
doxyfile_conf.set('h_input_filter', meson.source_root() / 'doc' / 'input-filter-h.sh')
update docs
2017-09-05 13:35:25 +02:00
Add doxygen docs
2017-05-30 19:46:51 +02:00
doxyfile = configure_file(input: 'Doxyfile.in',
output: 'Doxyfile',
require meson 0.49
2020-05-19 16:49:38 +02:00
configuration: doxyfile_conf)
Add doxygen docs
2017-05-30 19:46:51 +02:00
doc: add docdir option As patched in Gentoo. Fixes #1057
2021-04-15 21:45:53 +03:00
docdir = get_option('docdir')
if docdir == ''
docdir = pipewire_datadir / 'doc' / meson.project_name()
endif
Add doxygen docs
2017-05-30 19:46:51 +02:00
html_target = custom_target('pipewire-docs',
doc: link examples to Doxygen docs Include examples to the documentation, using Doxygen's example system.
2021-10-09 23:25:29 +03:00
input: [ doxyfile, examples_dox ] + inputs + cssfiles,
Add doxygen docs
2017-05-30 19:46:51 +02:00
output: [ 'html' ],
command: [ doxygen, doxyfile ],
install: true,
doc: add docdir option As patched in Gentoo. Fixes #1057
2021-04-15 21:45:53 +03:00
install_dir: docdir)
Reference in a new issue Copy permalink