From 77fad4ee13d407438714085ff16e219037377b64 Mon Sep 17 00:00:00 2001 From: Pauli Virtanen Date: Sat, 18 Nov 2023 15:13:05 +0200 Subject: [PATCH] doc: reorganize files Separate various autogen files from the documentation .dox files. Rename .dox files to match the intended tree structure. --- doc/{api.dox => dox/api/index.dox} | 1 + doc/{ => dox/api}/spa-buffer.dox | 0 doc/{ => dox/api}/spa-design.dox | 0 doc/{ => dox/api}/spa-index.dox | 0 doc/{ => dox/api}/spa-plugins.dox | 0 doc/{ => dox/api}/spa-pod.dox | 0 doc/{ => dox}/index.dox | 11 +-- .../internals/access.dox} | 0 .../internals/audio.dox} | 0 .../internals/daemon.dox} | 0 .../internals/design.dox} | 0 doc/{ => dox/internals}/dma-buf.dox | 0 doc/{pipewire.dox => dox/internals/index.dox} | 2 +- .../internals/library.dox} | 0 .../internals/midi.dox} | 0 .../internals/objects.dox} | 0 .../internals/portal.dox} | 0 .../internals/protocol.dox} | 0 doc/{ => dox/internals}/pulseaudio.dox | 0 .../internals/scheduling.dox} | 0 .../internals/session-manager.dox} | 0 doc/{pipewire-modules.dox => dox/modules.dox} | 2 +- doc/{ => dox}/overview.dox | 0 doc/{tutorial.dox => dox/tutorial/index.dox} | 2 +- doc/{ => dox/tutorial}/tutorial1.dox | 0 doc/{ => dox/tutorial}/tutorial2.dox | 0 doc/{ => dox/tutorial}/tutorial3.dox | 0 doc/{ => dox/tutorial}/tutorial4.dox | 0 doc/{ => dox/tutorial}/tutorial5.dox | 0 doc/{ => dox/tutorial}/tutorial6.dox | 0 doc/{ => examples}/tutorial1.c | 0 doc/{ => examples}/tutorial2.c | 0 doc/{ => examples}/tutorial3.c | 0 doc/{ => examples}/tutorial4.c | 0 doc/{ => examples}/tutorial5.c | 0 doc/{ => examples}/tutorial6.c | 0 doc/meson.build | 78 +++++++++---------- doc/pipewire-architecture.dox | 0 doc/pipewire-tools.dox.in | 7 -- doc/programs.dox.in | 7 ++ doc/{api-tree.dox => tree.dox} | 9 +++ 41 files changed, 60 insertions(+), 59 deletions(-) rename doc/{api.dox => dox/api/index.dox} (99%) rename doc/{ => dox/api}/spa-buffer.dox (100%) rename doc/{ => dox/api}/spa-design.dox (100%) rename doc/{ => dox/api}/spa-index.dox (100%) rename doc/{ => dox/api}/spa-plugins.dox (100%) rename doc/{ => dox/api}/spa-pod.dox (100%) rename doc/{ => dox}/index.dox (89%) rename doc/{pipewire-access.dox => dox/internals/access.dox} (100%) rename doc/{pipewire-audio.dox => dox/internals/audio.dox} (100%) rename doc/{pipewire-daemon.dox => dox/internals/daemon.dox} (100%) rename doc/{pipewire-design.dox => dox/internals/design.dox} (100%) rename doc/{ => dox/internals}/dma-buf.dox (100%) rename doc/{pipewire.dox => dox/internals/index.dox} (90%) rename doc/{pipewire-library.dox => dox/internals/library.dox} (100%) rename doc/{pipewire-midi.dox => dox/internals/midi.dox} (100%) rename doc/{pipewire-objects-design.dox => dox/internals/objects.dox} (100%) rename doc/{pipewire-portal.dox => dox/internals/portal.dox} (100%) rename doc/{pipewire-protocol.dox => dox/internals/protocol.dox} (100%) rename doc/{ => dox/internals}/pulseaudio.dox (100%) rename doc/{pipewire-scheduling.dox => dox/internals/scheduling.dox} (100%) rename doc/{pipewire-session-manager.dox => dox/internals/session-manager.dox} (100%) rename doc/{pipewire-modules.dox => dox/modules.dox} (98%) rename doc/{ => dox}/overview.dox (100%) rename doc/{tutorial.dox => dox/tutorial/index.dox} (89%) rename doc/{ => dox/tutorial}/tutorial1.dox (100%) rename doc/{ => dox/tutorial}/tutorial2.dox (100%) rename doc/{ => dox/tutorial}/tutorial3.dox (100%) rename doc/{ => dox/tutorial}/tutorial4.dox (100%) rename doc/{ => dox/tutorial}/tutorial5.dox (100%) rename doc/{ => dox/tutorial}/tutorial6.dox (100%) rename doc/{ => examples}/tutorial1.c (100%) rename doc/{ => examples}/tutorial2.c (100%) rename doc/{ => examples}/tutorial3.c (100%) rename doc/{ => examples}/tutorial4.c (100%) rename doc/{ => examples}/tutorial5.c (100%) rename doc/{ => examples}/tutorial6.c (100%) delete mode 100644 doc/pipewire-architecture.dox delete mode 100644 doc/pipewire-tools.dox.in create mode 100644 doc/programs.dox.in rename doc/{api-tree.dox => tree.dox} (93%) diff --git a/doc/api.dox b/doc/dox/api/index.dox similarity index 99% rename from doc/api.dox rename to doc/dox/api/index.dox index 880127e90..96268669c 100644 --- a/doc/api.dox +++ b/doc/dox/api/index.dox @@ -59,6 +59,7 @@ digraph API { It is common for clients to use both the \ref api_pw_core and the \ref api_pw_impl and both APIs are provided by the same library. +- \subpage page_spa - \subpage page_client_impl - \subpage page_proxy - \subpage page_streams diff --git a/doc/spa-buffer.dox b/doc/dox/api/spa-buffer.dox similarity index 100% rename from doc/spa-buffer.dox rename to doc/dox/api/spa-buffer.dox diff --git a/doc/spa-design.dox b/doc/dox/api/spa-design.dox similarity index 100% rename from doc/spa-design.dox rename to doc/dox/api/spa-design.dox diff --git a/doc/spa-index.dox b/doc/dox/api/spa-index.dox similarity index 100% rename from doc/spa-index.dox rename to doc/dox/api/spa-index.dox diff --git a/doc/spa-plugins.dox b/doc/dox/api/spa-plugins.dox similarity index 100% rename from doc/spa-plugins.dox rename to doc/dox/api/spa-plugins.dox diff --git a/doc/spa-pod.dox b/doc/dox/api/spa-pod.dox similarity index 100% rename from doc/spa-pod.dox rename to doc/dox/api/spa-pod.dox diff --git a/doc/index.dox b/doc/dox/index.dox similarity index 89% rename from doc/index.dox rename to doc/dox/index.dox index 451149219..93998e2ec 100644 --- a/doc/index.dox +++ b/doc/dox/index.dox @@ -17,7 +17,7 @@ PipeWire ships with the following components: - A \ref page_daemon that implements the IPC and graph processing. - An example \ref page_session_manager that manages objects in the \ref page_daemon. -- A set of \ref page_tools to introspect and use the \ref page_daemon. +- A set of \ref page_programs to introspect and use the \ref page_daemon. - A \ref page_library to develop PipeWire applications and plugins (\ref page_tutorial "tutorial"). - The \ref page_spa used by both the \ref page_daemon and in the \ref @@ -43,13 +43,4 @@ More information on how to configure and use PipeWire. - [Intoduction to PipeWire](https://bootlin.com/blog/an-introduction-to-pipewire/) - [A custom PipeWire node](https://bootlin.com/blog/a-custom-pipewire-node/) - -\page page_overview -\page page_pipewire -\page page_tools -\page page_pipewire_modules -\page page_api -\page page_spa -\page page_tutorial - */ diff --git a/doc/pipewire-access.dox b/doc/dox/internals/access.dox similarity index 100% rename from doc/pipewire-access.dox rename to doc/dox/internals/access.dox diff --git a/doc/pipewire-audio.dox b/doc/dox/internals/audio.dox similarity index 100% rename from doc/pipewire-audio.dox rename to doc/dox/internals/audio.dox diff --git a/doc/pipewire-daemon.dox b/doc/dox/internals/daemon.dox similarity index 100% rename from doc/pipewire-daemon.dox rename to doc/dox/internals/daemon.dox diff --git a/doc/pipewire-design.dox b/doc/dox/internals/design.dox similarity index 100% rename from doc/pipewire-design.dox rename to doc/dox/internals/design.dox diff --git a/doc/dma-buf.dox b/doc/dox/internals/dma-buf.dox similarity index 100% rename from doc/dma-buf.dox rename to doc/dox/internals/dma-buf.dox diff --git a/doc/pipewire.dox b/doc/dox/internals/index.dox similarity index 90% rename from doc/pipewire.dox rename to doc/dox/internals/index.dox index 0df12ef8a..f7152d61c 100644 --- a/doc/pipewire.dox +++ b/doc/dox/internals/index.dox @@ -1,4 +1,4 @@ -/** \page page_pipewire PipeWire Design +/** \page page_internals Internals # Internals diff --git a/doc/pipewire-library.dox b/doc/dox/internals/library.dox similarity index 100% rename from doc/pipewire-library.dox rename to doc/dox/internals/library.dox diff --git a/doc/pipewire-midi.dox b/doc/dox/internals/midi.dox similarity index 100% rename from doc/pipewire-midi.dox rename to doc/dox/internals/midi.dox diff --git a/doc/pipewire-objects-design.dox b/doc/dox/internals/objects.dox similarity index 100% rename from doc/pipewire-objects-design.dox rename to doc/dox/internals/objects.dox diff --git a/doc/pipewire-portal.dox b/doc/dox/internals/portal.dox similarity index 100% rename from doc/pipewire-portal.dox rename to doc/dox/internals/portal.dox diff --git a/doc/pipewire-protocol.dox b/doc/dox/internals/protocol.dox similarity index 100% rename from doc/pipewire-protocol.dox rename to doc/dox/internals/protocol.dox diff --git a/doc/pulseaudio.dox b/doc/dox/internals/pulseaudio.dox similarity index 100% rename from doc/pulseaudio.dox rename to doc/dox/internals/pulseaudio.dox diff --git a/doc/pipewire-scheduling.dox b/doc/dox/internals/scheduling.dox similarity index 100% rename from doc/pipewire-scheduling.dox rename to doc/dox/internals/scheduling.dox diff --git a/doc/pipewire-session-manager.dox b/doc/dox/internals/session-manager.dox similarity index 100% rename from doc/pipewire-session-manager.dox rename to doc/dox/internals/session-manager.dox diff --git a/doc/pipewire-modules.dox b/doc/dox/modules.dox similarity index 98% rename from doc/pipewire-modules.dox rename to doc/dox/modules.dox index 460b0934f..1eaaf4875 100644 --- a/doc/pipewire-modules.dox +++ b/doc/dox/modules.dox @@ -1,4 +1,4 @@ -/** \page page_pipewire_modules PipeWire Modules +/** \page page_modules Modules A PipeWire module is effectively a PipeWire client in an `.so` file that shares the \ref pw_context with the loading entity. Usually modules are diff --git a/doc/overview.dox b/doc/dox/overview.dox similarity index 100% rename from doc/overview.dox rename to doc/dox/overview.dox diff --git a/doc/tutorial.dox b/doc/dox/tutorial/index.dox similarity index 89% rename from doc/tutorial.dox rename to doc/dox/tutorial/index.dox index bc5372565..a4fc4d572 100644 --- a/doc/tutorial.dox +++ b/doc/dox/tutorial/index.dox @@ -1,6 +1,6 @@ /** \page page_tutorial Tutorial -Welcome to the PipeWire tutorial. The goal is to learn +Welcome to the PipeWire API tutorial. The goal is to learn PipeWire API step-by-step with simple short examples. - \subpage page_tutorial1 diff --git a/doc/tutorial1.dox b/doc/dox/tutorial/tutorial1.dox similarity index 100% rename from doc/tutorial1.dox rename to doc/dox/tutorial/tutorial1.dox diff --git a/doc/tutorial2.dox b/doc/dox/tutorial/tutorial2.dox similarity index 100% rename from doc/tutorial2.dox rename to doc/dox/tutorial/tutorial2.dox diff --git a/doc/tutorial3.dox b/doc/dox/tutorial/tutorial3.dox similarity index 100% rename from doc/tutorial3.dox rename to doc/dox/tutorial/tutorial3.dox diff --git a/doc/tutorial4.dox b/doc/dox/tutorial/tutorial4.dox similarity index 100% rename from doc/tutorial4.dox rename to doc/dox/tutorial/tutorial4.dox diff --git a/doc/tutorial5.dox b/doc/dox/tutorial/tutorial5.dox similarity index 100% rename from doc/tutorial5.dox rename to doc/dox/tutorial/tutorial5.dox diff --git a/doc/tutorial6.dox b/doc/dox/tutorial/tutorial6.dox similarity index 100% rename from doc/tutorial6.dox rename to doc/dox/tutorial/tutorial6.dox diff --git a/doc/tutorial1.c b/doc/examples/tutorial1.c similarity index 100% rename from doc/tutorial1.c rename to doc/examples/tutorial1.c diff --git a/doc/tutorial2.c b/doc/examples/tutorial2.c similarity index 100% rename from doc/tutorial2.c rename to doc/examples/tutorial2.c diff --git a/doc/tutorial3.c b/doc/examples/tutorial3.c similarity index 100% rename from doc/tutorial3.c rename to doc/examples/tutorial3.c diff --git a/doc/tutorial4.c b/doc/examples/tutorial4.c similarity index 100% rename from doc/tutorial4.c rename to doc/examples/tutorial4.c diff --git a/doc/tutorial5.c b/doc/examples/tutorial5.c similarity index 100% rename from doc/tutorial5.c rename to doc/examples/tutorial5.c diff --git a/doc/tutorial6.c b/doc/examples/tutorial6.c similarity index 100% rename from doc/tutorial6.c rename to doc/examples/tutorial6.c diff --git a/doc/meson.build b/doc/meson.build index c79b22824..4975917f4 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -14,39 +14,39 @@ else endif # Note: order here is how doxygen will expose the pages in the sidebar -# api-tree.dox should be first to determine ordering of Modules. +# tree.dox should be first to determine the ordering. extra_docs = [ - 'api-tree.dox', - 'index.dox', - 'overview.dox', - 'pipewire.dox', - 'pipewire-design.dox', - 'pipewire-access.dox', - 'pipewire-midi.dox', - 'pipewire-portal.dox', - 'pipewire-daemon.dox', - 'pipewire-library.dox', - 'pipewire-modules.dox', - 'pipewire-session-manager.dox', - 'pipewire-objects-design.dox', - 'pipewire-audio.dox', - 'pipewire-scheduling.dox', - 'pipewire-protocol.dox', - 'tutorial.dox', - 'tutorial1.dox', - 'tutorial2.dox', - 'tutorial3.dox', - 'tutorial4.dox', - 'tutorial5.dox', - 'tutorial6.dox', - 'api.dox', - 'spa-index.dox', - 'spa-plugins.dox', - 'spa-design.dox', - 'spa-pod.dox', - 'spa-buffer.dox', - 'pulseaudio.dox', - 'dma-buf.dox', + 'tree.dox', + 'dox/index.dox', + 'dox/overview.dox', + 'dox/modules.dox', + 'dox/internals/index.dox', + 'dox/internals/design.dox', + 'dox/internals/access.dox', + 'dox/internals/midi.dox', + 'dox/internals/portal.dox', + 'dox/internals/daemon.dox', + 'dox/internals/library.dox', + 'dox/internals/session-manager.dox', + 'dox/internals/objects.dox', + 'dox/internals/audio.dox', + 'dox/internals/scheduling.dox', + 'dox/internals/protocol.dox', + 'dox/internals/pulseaudio.dox', + 'dox/internals/dma-buf.dox', + 'dox/tutorial/index.dox', + 'dox/tutorial/tutorial1.dox', + 'dox/tutorial/tutorial2.dox', + 'dox/tutorial/tutorial3.dox', + 'dox/tutorial/tutorial4.dox', + 'dox/tutorial/tutorial5.dox', + 'dox/tutorial/tutorial6.dox', + 'dox/api/index.dox', + 'dox/api/spa-index.dox', + 'dox/api/spa-plugins.dox', + 'dox/api/spa-design.dox', + 'dox/api/spa-pod.dox', + 'dox/api/spa-buffer.dox', ] inputs = [] @@ -133,12 +133,12 @@ foreach m : manpages 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' ] +pw_programs_dox_conf = configuration_data() +pw_programs_dox_conf.set('man_subpages', '\n'.join(man_subpages)) +pw_programs_dox = configure_file(input: 'programs.dox.in', + output: 'programs.dox', + configuration: pw_programs_dox_conf) +input_dirs += [ 'doc/programs.dox' ] doxygen_layout = meson.project_source_root() / 'doc' / 'DoxygenLayout.xml' doxygen_filter_c = meson.project_source_root() / 'doc' / 'input-filter.sh' @@ -161,7 +161,7 @@ if docdir == '' endif html_target = custom_target('pipewire-docs', - input: [ doxyfile, doxygen_layout, examples_dox, pw_tools_dox, doxygen_filter_c, doxygen_filter_h ] + inputs + cssfiles + man_doxygen, + input: [ doxyfile, doxygen_layout, examples_dox, pw_programs_dox, doxygen_filter_c, doxygen_filter_h ] + inputs + cssfiles + man_doxygen, output: [ 'html' ], command: [ doxygen, doxyfile ], install: true, diff --git a/doc/pipewire-architecture.dox b/doc/pipewire-architecture.dox deleted file mode 100644 index e69de29bb..000000000 diff --git a/doc/pipewire-tools.dox.in b/doc/pipewire-tools.dox.in deleted file mode 100644 index e0bf11680..000000000 --- a/doc/pipewire-tools.dox.in +++ /dev/null @@ -1,7 +0,0 @@ -/** \page page_tools PipeWire Tools - -Manual pages: - -@man_subpages@ - -*/ diff --git a/doc/programs.dox.in b/doc/programs.dox.in new file mode 100644 index 000000000..1320abf0f --- /dev/null +++ b/doc/programs.dox.in @@ -0,0 +1,7 @@ +/** \page page_programs Programs + +Manual pages: + +@man_subpages@ + +*/ diff --git a/doc/api-tree.dox b/doc/tree.dox similarity index 93% rename from doc/api-tree.dox rename to doc/tree.dox index d0f22aa1b..50e03403b 100644 --- a/doc/api-tree.dox +++ b/doc/tree.dox @@ -1,5 +1,7 @@ /** +This determines the ordering of items in Doxygen sidebar. + \defgroup api_pw_core Core API \brief PipeWire Core API \{ @@ -120,4 +122,11 @@ Support interfaces provided by host \{ \} +\page page_overview +\page page_modules +\page page_programs +\page page_internals +\page page_api +\page page_tutorial + */