mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2025-10-29 05:40:27 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
pipewire/doc/meson.build

168 lines
5.5 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())
treewide: meson.build: use project_{build,source}_root() Use `meson.project_{build,source}_root()` instead of `meson.{build,source}_root()` because those functions do not work as expected when used inside a subproject, and they have been deprecated in meson 0.56.0.
2021-12-28 16:35:20 +01:00
doxyfile_conf.set('top_srcdir', meson.project_source_root())
doxyfile_conf.set('top_builddir', meson.project_build_root())
doc: specify Doxygen OUTPUT_DIRECTORY as an absolute path Currently, doxygen is run by ninja in the top-level build directory, therefore the "doc" folder is always created there. However, when pipewire is built as a subproject, it should not touch the top-level build directory because it can cause conflicts and because the documentation won't be created where meson thinks it will be, so the "doxygen" target will always be dirty and installation will fail.
2023-01-14 22:02:13 +01:00
doxyfile_conf.set('output_directory', meson.current_build_dir())
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-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 some more docs
2023-05-15 11:44:41 +02:00
'pipewire-scheduling.dox',
doc: document registry events and methods
2023-05-16 11:21:03 +02:00
'pipewire-protocol.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
treewide: meson.build: use project_{build,source}_root() Use `meson.project_{build,source}_root()` instead of `meson.{build,source}_root()` because those functions do not work as expected when used inside a subproject, and they have been deprecated in meson 0.56.0.
2021-12-28 16:35:20 +01:00
inputs += meson.project_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
treewide: meson.build: use project_{build,source}_root() Use `meson.project_{build,source}_root()` instead of `meson.{build,source}_root()` because those functions do not work as expected when used inside a subproject, and they have been deprecated in meson 0.56.0.
2021-12-28 16:35:20 +01:00
inputs += meson.project_source_root() / 'src' / 'pipewire' / h
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
endforeach
foreach h : pipewire_ext_headers
treewide: meson.build: use project_{build,source}_root() Use `meson.project_{build,source}_root()` instead of `meson.{build,source}_root()` because those functions do not work as expected when used inside a subproject, and they have been deprecated in meson 0.56.0.
2021-12-28 16:35:20 +01:00
inputs += meson.project_source_root() / 'src' / 'pipewire' / 'extensions' / h
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
endforeach
foreach h : pipewire_ext_sm_headers
treewide: meson.build: use project_{build,source}_root() Use `meson.project_{build,source}_root()` instead of `meson.{build,source}_root()` because those functions do not work as expected when used inside a subproject, and they have been deprecated in meson 0.56.0.
2021-12-28 16:35:20 +01:00
inputs += meson.project_source_root() / 'src' / 'pipewire' / 'extensions' / h
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
endforeach
foreach h : pipewire_sources
treewide: meson.build: use project_{build,source}_root() Use `meson.project_{build,source}_root()` instead of `meson.{build,source}_root()` because those functions do not work as expected when used inside a subproject, and they have been deprecated in meson 0.56.0.
2021-12-28 16:35:20 +01:00
inputs += meson.project_source_root() / 'src' / 'pipewire' / h
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
endforeach
foreach h : module_sources
treewide: meson.build: use project_{build,source}_root() Use `meson.project_{build,source}_root()` instead of `meson.{build,source}_root()` because those functions do not work as expected when used inside a subproject, and they have been deprecated in meson 0.56.0.
2021-12-28 16:35:20 +01:00
inputs += meson.project_source_root() / 'src' / 'modules' / h
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
endforeach
treewide: meson.build: use project_{build,source}_root() Use `meson.project_{build,source}_root()` instead of `meson.{build,source}_root()` because those functions do not work as expected when used inside a subproject, and they have been deprecated in meson 0.56.0.
2021-12-28 16:35:20 +01:00
inputs += meson.project_source_root() / 'test' / 'pwtest.h'
input_dirs = [ meson.project_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 = [
treewide: meson.build: use project_{build,source}_root() Use `meson.project_{build,source}_root()` instead of `meson.{build,source}_root()` because those functions do not work as expected when used inside a subproject, and they have been deprecated in meson 0.56.0.
2021-12-28 16:35:20 +01:00
meson.project_source_root() / 'src',
meson.project_source_root() / 'spa' / 'include',
meson.project_source_root(),
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
]
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 = [
treewide: meson.build: use project_{build,source}_root() Use `meson.project_{build,source}_root()` instead of `meson.{build,source}_root()` because those functions do not work as expected when used inside a subproject, and they have been deprecated in meson 0.56.0.
2021-12-28 16:35:20 +01:00
meson.project_source_root() / 'doc' / 'doxygen-awesome.css',
meson.project_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
]
meson: ensure all examples are included in doc Move declaration of examples to use same file lists for build and docs.
2021-10-31 14:17:58 +02:00
foreach h : examples
example_files += [h + '.c']
endforeach
foreach h : spa_examples
example_files += ['spa/examples/' + h + '.c']
endforeach
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_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: include manpages in html docs Include manpages as raw text in html docs. Simple and readable enough...
2022-01-20 21:06:54 +02:00
man_doxygen = []
man_subpages = []
foreach m : manpages
manconf = configuration_data()
pagename = 'page_man_' + m.split('.rst.in').get(0).replace('.', '_').replace('-', '_')
filename = m.split('.rst.in').get(0) + '.dox'
manconf.set('pagename', pagename)
manconf.set('title', m.split('.rst.in').get(0).replace('.1','').replace('.5',''))
manconf.set('filename', meson.project_source_root() / 'man' / m)
manfile = configure_file(input: 'manpage.dox.in',
output: filename,
configuration: manconf)
man_doxygen += [manfile]
man_subpages += ['- \subpage ' + pagename]
input_dirs += [ 'doc/' + filename ]
endforeach
pw_tools_dox_conf = configuration_data()
pw_tools_dox_conf.set('man_subpages', '\n'.join(man_subpages))
pw_tools_dox = configure_file(input: 'pipewire-tools.dox.in',
output: 'pipewire-tools.dox',
configuration: pw_tools_dox_conf)
input_dirs += [ 'doc/pipewire-tools.dox' ]
doc: fixup some Doxygen autogen issues Don't show page sections in left sidebar, it's confusing. Rename Modules -> API Reference in sidebar. Indicate visually the sidebar entries are collapsible. Fix spa_pod_json grouping. Move tools page to top level. Fix page ordering.
2023-11-04 11:26:27 +02:00
doxygen_layout = meson.project_source_root() / 'doc' / 'DoxygenLayout.xml'
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: fixup some Doxygen autogen issues Don't show page sections in left sidebar, it's confusing. Rename Modules -> API Reference in sidebar. Indicate visually the sidebar entries are collapsible. Fix spa_pod_json grouping. Move tools page to top level. Fix page ordering.
2023-11-04 11:26:27 +02:00
doxyfile_conf.set('layout', doxygen_layout)
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))
treewide: meson.build: use project_{build,source}_root() Use `meson.project_{build,source}_root()` instead of `meson.{build,source}_root()` because those functions do not work as expected when used inside a subproject, and they have been deprecated in meson 0.56.0.
2021-12-28 16:35:20 +01:00
doxyfile_conf.set('c_input_filter', meson.project_source_root() / 'doc' / 'input-filter.sh')
doxyfile_conf.set('h_input_filter', meson.project_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: fixup some Doxygen autogen issues Don't show page sections in left sidebar, it's confusing. Rename Modules -> API Reference in sidebar. Indicate visually the sidebar entries are collapsible. Fix spa_pod_json grouping. Move tools page to top level. Fix page ordering.
2023-11-04 11:26:27 +02:00
input: [ doxyfile, doxygen_layout, examples_dox, pw_tools_dox ] + inputs + cssfiles + man_doxygen,
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