From d564baafed0863813a87d872f8663134e74228c8 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 14 May 2023 20:03:30 -0400 Subject: Clean up documentation and remove junk files from install --- doc/c/Doxyfile.in | 31 ---------- doc/c/api/meson.build | 9 --- doc/c/index.rst | 14 ----- doc/c/meson.build | 54 ----------------- doc/c/overview.rst | 22 ------- doc/c/plugins.rst | 94 ------------------------------ doc/c/uis.rst | 25 -------- doc/c/world.rst | 157 -------------------------------------------------- doc/c/xml/meson.build | 21 ------- 9 files changed, 427 deletions(-) delete mode 100644 doc/c/Doxyfile.in delete mode 100644 doc/c/api/meson.build delete mode 100644 doc/c/index.rst delete mode 100644 doc/c/meson.build delete mode 100644 doc/c/overview.rst delete mode 100644 doc/c/plugins.rst delete mode 100644 doc/c/uis.rst delete mode 100644 doc/c/world.rst delete mode 100644 doc/c/xml/meson.build (limited to 'doc/c') diff --git a/doc/c/Doxyfile.in b/doc/c/Doxyfile.in deleted file mode 100644 index 2ca5694..0000000 --- a/doc/c/Doxyfile.in +++ /dev/null @@ -1,31 +0,0 @@ -# Copyright 2021-2022 David Robillard -# SPDX-License-Identifier: 0BSD OR ISC - -PROJECT_NAME = Lilv -PROJECT_BRIEF = "A library for simple use of LV2 plugins" - -QUIET = YES -WARN_AS_ERROR = NO -WARN_IF_UNDOCUMENTED = NO -WARN_NO_PARAMDOC = NO - -JAVADOC_AUTOBRIEF = YES - -CASE_SENSE_NAMES = YES -HIDE_IN_BODY_DOCS = YES -REFERENCES_LINK_SOURCE = NO - -GENERATE_HTML = NO -GENERATE_LATEX = NO -GENERATE_XML = YES -XML_PROGRAMLISTING = NO -SHOW_FILES = NO - -MACRO_EXPANSION = YES -PREDEFINED = LILV_API LILV_DEPRECATED - -RECURSIVE = YES -STRIP_FROM_PATH = @LILV_SRCDIR@ -INPUT = @LILV_SRCDIR@/include/lilv/lilv.h - -OUTPUT_DIRECTORY = @DOX_OUTPUT@ diff --git a/doc/c/api/meson.build b/doc/c/api/meson.build deleted file mode 100644 index 8c8293b..0000000 --- a/doc/c/api/meson.build +++ /dev/null @@ -1,9 +0,0 @@ -# Copyright 2021-2022 David Robillard -# SPDX-License-Identifier: 0BSD OR ISC - -c_lilv_rst = custom_target( - 'lilv.rst', - command: [sphinxygen, '-f', '@INPUT0@', '@OUTDIR@'], - input: [c_index_xml] + c_rst_files, - output: 'lilv.rst', -) diff --git a/doc/c/index.rst b/doc/c/index.rst deleted file mode 100644 index e93b0e8..0000000 --- a/doc/c/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. - Copyright 2020-2022 David Robillard - SPDX-License-Identifier: ISC - -#### -Lilv -#### - -.. include:: summary.rst - -.. toctree:: - - overview - api/lilv diff --git a/doc/c/meson.build b/doc/c/meson.build deleted file mode 100644 index 53e69dc..0000000 --- a/doc/c/meson.build +++ /dev/null @@ -1,54 +0,0 @@ -# Copyright 2021-2022 David Robillard -# SPDX-License-Identifier: 0BSD OR ISC - -config = configuration_data() -config.set('LILV_VERSION', meson.project_version()) - -conf_py = configure_file( - configuration: config, - input: files('../conf.py.in'), - output: 'conf.py', -) - -configure_file( - copy: true, - input: files('../summary.rst'), - output: 'summary.rst', -) - -c_rst_files = files( - 'index.rst', - 'overview.rst', - 'plugins.rst', - 'uis.rst', - 'world.rst', -) - -foreach f : c_rst_files - configure_file(copy: true, input: f, output: '@PLAINNAME@') -endforeach - -subdir('xml') -subdir('api') - -docs = custom_target( - 'singlehtml', - build_by_default: true, - command: [sphinx_build, '-M', 'singlehtml', '@OUTDIR@', '@OUTDIR@', - '-E', '-q', '-t', 'singlehtml'], - input: [c_rst_files, c_lilv_rst, c_index_xml], - install: true, - install_dir: docdir / 'lilv-0', - output: 'singlehtml', -) - -docs = custom_target( - 'html', - build_by_default: true, - command: [sphinx_build, '-M', 'html', '@OUTDIR@', '@OUTDIR@', - '-E', '-q', '-t', 'html'], - input: [c_rst_files, c_lilv_rst, c_index_xml], - install: true, - install_dir: docdir / 'lilv-0', - output: 'html', -) diff --git a/doc/c/overview.rst b/doc/c/overview.rst deleted file mode 100644 index 17ebec9..0000000 --- a/doc/c/overview.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. - Copyright 2020-2022 David Robillard - SPDX-License-Identifier: ISC - -.. default-domain:: c -.. highlight:: c - -######## -Overview -######## - -The complete API is declared in ``lilv.h``: - -.. code-block:: c - - #include - -.. toctree:: - - world - plugins - uis diff --git a/doc/c/plugins.rst b/doc/c/plugins.rst deleted file mode 100644 index c7ad547..0000000 --- a/doc/c/plugins.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. - Copyright 2020-2022 David Robillard - SPDX-License-Identifier: ISC - -.. default-domain:: c -.. highlight:: c - -####### -Plugins -####### - -After bundles are loaded, -all discovered plugins can be accessed via :func:`lilv_world_get_all_plugins`: - -.. code-block:: c - - LilvPlugins* plugins = lilv_world_get_all_plugins(world); - -:struct:`LilvPlugins` is a collection of plugins that can be accessed by index or plugin URI. -The convenicne macro :macro:`LILV_FOREACH` is provided to make iterating over collections simple. -For example, to print the URI of every plugin: - -.. code-block:: c - - LILV_FOREACH (plugins, i, list) { - const LilvPlugin* p = lilv_plugins_get(list, i); - printf("%s\n", lilv_node_as_uri(lilv_plugin_get_uri(p))); - } - } - -More typically, -you want to load a specific plugin, -which can be done with :func:`lilv_plugins_get_by_uri`: - -.. code-block:: c - - LilvNode* plugin_uri = lilv_new_uri(world, "http://example.org/Osc"); - - const LilvPlugin* plugin = lilv_plugins_get_by_uri(list, plugin_uri); - -:struct:`LilvPlugin` has various accessors that can be used to get information about the plugin. -See the :doc:`API reference ` for details. - -********* -Instances -********* - -:struct:`LilvPlugin` only represents the data of the plugin, -it does not load or access the actual plugin code. -To do that, you must instantiate a plugin to create :struct:`LilvInstance`: - -.. code-block:: c - - LilvInstance* instance = lilv_plugin_instantiate(plugin, 48000.0, NULL); - -Connecting Ports -================ - -Before running a plugin instance, its ports must be connected to some data. -This is done with :func:`lilv_instance_connect_port`. -Assuming the plugins has two control input ports and one audio output port, -in that order: - -.. code-block:: c - - float control_in_1 = 0.0f; - float control_in_2 = 0.0f; - - float audio_out[128]; - - lilv_instance_connect_port(instance, 0, &control_in_1); - lilv_instance_connect_port(instance, 1, &control_in_2); - lilv_instance_connect_port(instance, 2, &audio_out); - -Processing Data -=============== - -Once the ports are connected, the instance can be activated and run: - -.. code-block:: c - - lilv_instance_activate(instance); - - lilv_instance_run(instance, 128); - // Copy buffers around and probably run several times here... - - lilv_instance_deactivate(instance); - -Once you are done with an instance, -it can be destroyed with :func:`lilv_instance_free`: - -.. code-block:: c - - lilv_instance_free(instance); diff --git a/doc/c/uis.rst b/doc/c/uis.rst deleted file mode 100644 index 1169060..0000000 --- a/doc/c/uis.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. - Copyright 2020-2022 David Robillard - SPDX-License-Identifier: ISC - -.. default-domain:: c -.. highlight:: c - -############### -User Interfaces -############### - -Plugins may have custom user interfaces, or `UIs`, -which are installed in bundles just like plugins. - -The available UIs for a plugin can be accessed with :func:`lilv_plugin_get_uis`: - -.. code-block:: c - - LilvUIs* uis = lilv_plugin_get_uis(plugin); - -:struct:`LilvUIs` is a collection much like `LilvPlugins`, -except it is of course a set of :struct:`LilvUI` rather than a set of :struct:`LilvPlugin`. -Also like plugins, -the :struct:`LilvUI` class has various accessors that can be used to get information about the UI. -See the :doc:`API reference ` for details. diff --git a/doc/c/world.rst b/doc/c/world.rst deleted file mode 100644 index 8b71165..0000000 --- a/doc/c/world.rst +++ /dev/null @@ -1,157 +0,0 @@ -.. - Copyright 2020-2022 David Robillard - SPDX-License-Identifier: ISC - -.. default-domain:: c -.. highlight:: c - -##### -World -##### - -The world is the top-level object which represents an instance of Lilv. -It is used to discover and load LV2 data, -and stores an internal cache of loaded data for fast searching. - -An application typically has a single world, -which is constructed once on startup and used throughout the application's lifetime. - -************ -Construction -************ - -A world must be created before anything else. -A world is created with :func:`lilv_world_new`, for example: - -.. code-block:: c - - LilvWorld* world = lilv_world_new(); - -*************** -Setting Options -*************** - -Various options to control Lilv's behavior can be set with :func:`lilv_world_set_option`. -The currently supported options are :c:macro:`LILV_OPTION_FILTER_LANG`, -:c:macro:`LILV_OPTION_DYN_MANIFEST`, and :c:macro:`LILV_OPTION_LV2_PATH`. - -For example, to set the LV2 path to only load plugins bundled in the application: - -.. code-block:: c - - LilvNode* lv2_path = lilv_new_file_uri(world, NULL, "/myapp/lv2"); - - lilv_world_set_option(world, LILV_OPTION_LV2_PATH, lv2_path); - -************ -Loading Data -************ - -Before using anything, data must be loaded from disk. -All LV2 data (plugins, UIs, specifications, presets, and so on) is installed in `bundles`, -a standard directory format - -Discovering and Loading Bundles -=============================== - -Typical hosts will simply load all bundles in the standard LV2 locations on the system: - -.. code-block:: c - - lilv_world_load_all(world); - -This will discover all bundles on the system, -as well as load the required data defined in any discovered specifications. - -It is also possible to load a specific bundle: - -.. code-block:: c - - LilvNode* bundle_uri = lilv_new_file_uri(world, NULL, "/some/plugin.lv2"); - - lilv_world_load_bundle(world, bundle_uri); - -The LV2 specification itself is also installed in bundles, -so if you are not using :func:`lilv_world_load_all`, -it is necessary to manually load the discovered specification data: - -.. code-block:: c - - lilv_world_load_specifications(world); - lilv_world_load_plugin_classes(world); - -************* -Querying Data -************* - -The world contains a model of all the loaded data in memory which can be queried. - -Data Model -========== - -LV2 data is a set of "statements", -where a statement is a bit like a simple machine-readable sentence. -The "subject" and "object" are as in natural language, -and the "predicate" is like the verb, but more general. - -For example, we could make a statement about a plugin in english: - - MyOsc has the name "Super Oscillator" - -We can break this statement into 3 pieces like so: - -.. list-table:: - :header-rows: 1 - - * - Subject - - Predicate - - Object - * - MyOsc - - has the name - - "My Super Oscillator" - -Statements use URIs to identify things. -In this case, we assume that this plugin has the URI ``http://example.org/Osc``. -The LV2 specification defines that ``http://usefulinc.com/ns/doap#name`` is the property used to describe a plugin's name. -So, this statement is: - -.. list-table:: - :header-rows: 1 - - * - Subject - - Predicate - - Object - * - ``http://example.org/Osc`` - - ``http://usefulinc.com/ns/doap#name`` - - "My Oscillator" - -Finding Values -============== - -Based on this model, you can find all values that match a certain pattern. -Patterns are just statements, -but with ``NULL`` used as a wildcard that matches anything. -So, for example, you can get the name of a plugin using :func:`lilv_world_find_nodes`: - -.. code-block:: c - - LilvNode* plugin_uri = lilv_new_uri(world, "http://example.org/Osc"); - LilvNode* doap_name = lilv_new_uri(world, "http://usefulinc.com/ns/doap#name"); - - LilvNodes* values = lilv_world_find_nodes(world, plugin_uri, doap_name, NULL); - -Note that a set of values is returned, -because some properties may have several values. -When you are only interested in one value, -you can use the simpler :func:`lilv_world_get` instead: - -.. code-block:: c - - LilvNode* value = lilv_world_get(world, plugin_uri, doap_name, NULL); - -If you are only interested if a value exists at all, -use :func:`lilv_world_ask`: - -.. code-block:: c - - bool has_name = lilv_world_ask(world, plugin_uri, doap_name, NULL); diff --git a/doc/c/xml/meson.build b/doc/c/xml/meson.build deleted file mode 100644 index dc234f3..0000000 --- a/doc/c/xml/meson.build +++ /dev/null @@ -1,21 +0,0 @@ -# Copyright 2021-2022 David Robillard -# SPDX-License-Identifier: 0BSD OR ISC - -doxygen = find_program('doxygen') - -config = configuration_data() -config.set('LILV_SRCDIR', lilv_src_root) -config.set('DOX_OUTPUT', meson.current_build_dir() / '..') - -c_doxyfile = configure_file( - configuration: config, - input: files('../Doxyfile.in'), - output: 'Doxyfile', -) - -c_index_xml = custom_target( - 'index.xml', - command: [doxygen, '@INPUT0@'], - input: [c_doxyfile] + c_headers, - output: 'index.xml', -) -- cgit v1.2.1