aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/_static/custom.css95
-rw-r--r--doc/_templates/about.html57
-rw-r--r--doc/c/index.rst9
-rw-r--r--doc/c/overview.rst8
-rw-r--r--doc/c/reference.rst18
-rw-r--r--doc/c/wscript7
-rw-r--r--doc/conf.py.in79
-rw-r--r--doc/cpp/c-reference.rst20
-rw-r--r--doc/cpp/cpp-reference.rst18
-rw-r--r--doc/cpp/index.rst11
-rw-r--r--doc/cpp/overview.rst1
-rw-r--r--doc/cpp/wscript8
-rw-r--r--doc/deployment.rst16
-rw-r--r--doc/pugl.rst26
14 files changed, 73 insertions, 300 deletions
diff --git a/doc/_static/custom.css b/doc/_static/custom.css
deleted file mode 100644
index 60aa759..0000000
--- a/doc/_static/custom.css
+++ /dev/null
@@ -1,95 +0,0 @@
-div.document {
- margin: 0;
-}
-
-div.body {
- margin-top: 2em;
-}
-
-div.sphinxsidebarwrapper {
- background: #EEE;
-}
-
-div.sphinxsidebarwrapper p.blurb {
- text-align: center;
-}
-
-div.sphinxsidebarwrapper span.logo {
- display: block;
- text-align: center;
- font-family: Georgia, serif;
- padding: 0;
- font-size: 180%;
-}
-
-div.sphinxsidebar a {
- border-width: 0;
-}
-
-div.sphinxsidebar li {
- color: #444;
-}
-
-div.section {
- margin-top: 2.5em;
-}
-
-a.reference {
- border-bottom: none;
-}
-
-code.xref {
- font-weight: normal;
- background-color: #F8F8F8;
- padding: 0.1em 0 0.1em 0;
-}
-
-div.section > dl.c > dt:first-child,
-div.section > dl.cpp > dt:first-child {
- background-color: #F8F8F8;
- font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
- font-size: 0.9em;
- font-weight: normal;
- margin-bottom: 0.5em;
- padding: 0.1em 0 0.1em 0;
-}
-
-tt.descname, tt.descclassname, code.descname, code.descclassname {
- font-size: 0.9em;
-}
-
-dl.member {
- margin-top: 0.5em;
-}
-
-dl.enumerator {
- margin-top: 0.5em;
-}
-
-dl.field-list > dt {
- padding-left: 0;
-}
-
-pre, tt, code {
- background-color: #F8F8F8;
-}
-
-.toctree-l1 {
- margin-top: 1.0em;
-}
-
-img.logo {
- width: 6em;
-}
-
-.class {
- padding-top: 1.5em;
-}
-
-.exception {
- padding-top: 1.5em;
-}
-
-.class > dd > dl.function {
- padding-top: 1.0em;
-}
diff --git a/doc/_templates/about.html b/doc/_templates/about.html
deleted file mode 100644
index 5bbadbe..0000000
--- a/doc/_templates/about.html
+++ /dev/null
@@ -1,57 +0,0 @@
-{% if theme_logo %}
-<p class="logo">
- <a href="{{ pathto(master_doc) }}">
- <img class="logo" src="{{ pathto('_static/' ~ theme_logo, 1) }}" alt="Logo"/>
- {% if theme_logo_name|lower == 'true' %}
- <span class="logo logo-name">{{ project }}</span>
- {% endif %}
- </a>
-</p>
-{% else %}
-<h1 class="logo"><a href="{{ pathto(master_doc) }}">{{ project }}</a></h1>
-{% endif %}
-
-{% if theme_description %}
-<p class="blurb">{{ theme_description }}</p>
-{% endif %}
-
-{% if theme_github_user and theme_github_repo %}
-{% if theme_github_button|lower == 'true' %}
-<p>
-<iframe src="https://ghbtns.com/github-btn.html?user={{ theme_github_user }}&repo={{ theme_github_repo }}&type={{ theme_github_type }}&count={{ theme_github_count }}&size=large&v=2"
- allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
-</p>
-{% endif %}
-{% endif %}
-
-{% if theme_travis_button|lower != 'false' %}
-{% if theme_travis_button|lower == 'true' %}
- {% set path = theme_github_user + '/' + theme_github_repo %}
-{% else %}
- {% set path = theme_travis_button %}
-{% endif %}
-<p>
-<a class="badge" href="https://travis-ci.org/{{ path }}">
- <img
- alt="https://secure.travis-ci.org/{{ path }}.svg?branch={{ theme_badge_branch }}"
- src="https://secure.travis-ci.org/{{ path }}.svg?branch={{ theme_badge_branch }}"
- />
-</a>
-</p>
-{% endif %}
-
-{% if theme_codecov_button|lower != 'false' %}
-{% if theme_codecov_button|lower == 'true' %}
- {% set path = theme_github_user + '/' + theme_github_repo %}
-{% else %}
- {% set path = theme_codecov_button %}
-{% endif %}
-<p>
-<a class="badge" href="https://codecov.io/github/{{ path }}">
- <img
- alt="https://codecov.io/github/{{ path }}/coverage.svg?branch={{ theme_badge_branch }}"
- src="https://codecov.io/github/{{ path }}/coverage.svg?branch={{ theme_badge_branch }}"
- />
-</a>
-</p>
-{% endif %}
diff --git a/doc/c/index.rst b/doc/c/index.rst
index 6f046de..020cf32 100644
--- a/doc/c/index.rst
+++ b/doc/c/index.rst
@@ -1,6 +1,11 @@
+####
+Pugl
+####
+
+.. include:: summary.rst
+
.. toctree::
- pugl
deployment
overview
- reference
+ api/pugl
diff --git a/doc/c/overview.rst b/doc/c/overview.rst
index f597aab..4bd024d 100644
--- a/doc/c/overview.rst
+++ b/doc/c/overview.rst
@@ -9,6 +9,12 @@ The Pugl API revolves around two main objects: the `world` and the `view`.
An application creates a world to manage top-level state,
then creates one or more views to display.
+The core API (excluding backend-specific components) is declared in ``pugl.h``:
+
+.. code-block:: c
+
+ #include <pugl/pugl.h>
+
.. toctree::
world
@@ -16,3 +22,5 @@ then creates one or more views to display.
events
event-loop
shutting-down
+
+.. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/
diff --git a/doc/c/reference.rst b/doc/c/reference.rst
deleted file mode 100644
index 21a187f..0000000
--- a/doc/c/reference.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-#############
-API Reference
-#############
-
-This section contains the generated documentation for all symbols in the public
-API.
-
-.. toctree::
-
- api/status
- api/world
- api/view
- api/events
-
- api/cairo
- api/gl
- api/stub
- api/vulkan
diff --git a/doc/c/wscript b/doc/c/wscript
index 389c43f..dc97f6e 100644
--- a/doc/c/wscript
+++ b/doc/c/wscript
@@ -6,15 +6,12 @@ def build(bld):
files = [
("../../resources/pugl.svg", "sphinx/_static/pugl.svg"),
- ("../_static/custom.css", "sphinx/_static/custom.css"),
- ("../_templates/about.html", "sphinx/_templates/about.html"),
("../deployment.rst", "sphinx/deployment.rst"),
- ("../pugl.rst", "sphinx/pugl.rst"),
+ ("../summary.rst", "sphinx/summary.rst"),
("event-loop.rst", "sphinx/event-loop.rst"),
("events.rst", "sphinx/events.rst"),
("index.rst", "sphinx/index.rst"),
("overview.rst", "sphinx/overview.rst"),
- ("reference.rst", "sphinx/reference.rst"),
("shutting-down.rst", "sphinx/shutting-down.rst"),
("view.rst", "sphinx/view.rst"),
("world.rst", "sphinx/world.rst"),
@@ -44,5 +41,5 @@ def build(bld):
bld(features="sphinx",
sphinx_source=bld.path.get_bld().make_node("sphinx"),
sphinx_output_format="singlehtml",
- sphinx_options=["-E", "-q"],
+ sphinx_options=["-E", "-q", "-t", "singlehtml"],
install_path=doc_dir + "c/singlehtml/")
diff --git a/doc/conf.py.in b/doc/conf.py.in
index 9ca7bfa..d6c9160 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -7,20 +7,12 @@ release = "@PUGL_VERSION@"
# General configuration
+exclude_patterns = ["xml"]
language = "en"
-
-extensions = [
- # 'breathe',
- # 'sphinx_rtd_theme',
- # 'sphinx.ext.autodoc',
- # 'sphinx.ext.doctest',
- # 'sphinx.ext.napoleon',
- # 'sphinx.ext.viewcode',
-]
-
-# Enable nitpicky mode to get warnings about broken links
-# Unfortunately this means we need to explicitly ignore everything external
nitpicky = True
+pygments_style = "friendly"
+
+# Ignore everything opaque or external for nitpicky mode
_opaque = [
"PFN_vkGetDeviceProcAddr",
"PFN_vkGetInstanceProcAddr",
@@ -36,53 +28,58 @@ _opaque = [
"uint32_t",
"uintptr_t",
]
+
_c_nitpick_ignore = map(lambda x: ("c:identifier", x), _opaque)
_cpp_nitpick_ignore = map(lambda x: ("cpp:identifier", x), _opaque)
nitpick_ignore = list(_c_nitpick_ignore) + list(_cpp_nitpick_ignore)
-templates_path = ["_templates"]
-
-pygments_style = "friendly"
-
# C++
cpp_index_common_prefix = ["pugl::"]
# HTML output
-exclude_patterns = ["xml"]
+html_copy_source = False
+html_short_title = "Pugl"
html_static_path = ["_static"]
+html_theme = "sphinx_lv2_theme"
-html_theme = "alabaster"
-# html_theme = "sphinx_rtd_theme"
-
-if html_theme == "alabaster":
+if tags.has('singlehtml'):
+ html_sidebars = {
+ "**": [
+ "globaltoc.html",
+ ]
+ }
html_theme_options = {
+ "body_max_width": "50em",
+ "body_min_width": "50em",
"description": "A minimal portable API for embeddable GUIs.",
- "donate_url": "http://drobilla.net/pages/donate.html",
- # "github_repo": "pugl",
- # "github_user": "lv2",
+ "show_footer_version": True,
+ "show_logo_version": False,
"logo": "pugl.svg",
"logo_name": True,
- "logo_text_align": "center",
- "page_width": "80em - 20em",
- "sidebar_width": "20em",
- }
-
- html_sidebars = {
- "**": [
- "about.html",
- "localtoc.html",
- "donate.html",
- ]
+ "logo_width": "8em",
+ "nosidebar": False,
+ "page_width": "80em",
+ "sidebar_width": "16em",
+ "globaltoc_maxdepth": 3,
+ "globaltoc_collapse": False,
}
-elif html_theme == "sphinx_rtd_theme":
-
+else:
html_theme_options = {
- "sticky_navigation": False,
- "collapse_navigation": False,
- "navigation_depth": 4,
- "display_version": True,
+ "body_max_width": "60em",
+ "body_min_width": "40em",
+ "description": "A minimal portable API for embeddable GUIs.",
+ "show_footer_version": True,
+ "show_logo_version": False,
+ "logo": "pugl.svg",
+ "logo_name": True,
+ "logo_width": "8em",
+ "nosidebar": True,
+ "page_width": "60em",
+ "sidebar_width": "14em",
+ "globaltoc_maxdepth": 1,
+ "globaltoc_collapse": True,
}
diff --git a/doc/cpp/c-reference.rst b/doc/cpp/c-reference.rst
deleted file mode 100644
index 546e4d3..0000000
--- a/doc/cpp/c-reference.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-###############
-C API Reference
-###############
-
-This section contains the generated documentation for all symbols in the public
-C API.
-It is included here because some C++ wrapper definitions refer to the underlying C symbols,
-but direct use of the C API should not be necessary in C++ applications.
-
-.. toctree::
-
- api/status
- api/world
- api/view
- api/events
-
- api/cairo
- api/gl
- api/stub
- api/vulkan
diff --git a/doc/cpp/cpp-reference.rst b/doc/cpp/cpp-reference.rst
deleted file mode 100644
index 96c523c..0000000
--- a/doc/cpp/cpp-reference.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-#################
-C++ API Reference
-#################
-
-This section contains the generated documentation for all symbols in the public
-C++ API.
-
-.. toctree::
-
- api/statusxx
- api/worldxx
- api/viewxx
- api/eventsxx
-
- api/cairoxx
- api/glxx
- api/stubxx
- api/vulkanxx
diff --git a/doc/cpp/index.rst b/doc/cpp/index.rst
index c3d330e..b11d028 100644
--- a/doc/cpp/index.rst
+++ b/doc/cpp/index.rst
@@ -1,7 +1,12 @@
+####
+Pugl
+####
+
+.. include:: summary.rst
+
.. toctree::
- pugl
deployment
overview
- cpp-reference
- c-reference
+ api/pugl
+ api/puglxx
diff --git a/doc/cpp/overview.rst b/doc/cpp/overview.rst
index 4ffc3da..1928fba 100644
--- a/doc/cpp/overview.rst
+++ b/doc/cpp/overview.rst
@@ -33,4 +33,3 @@ then creates one or more views to display.
view
events
event-loop
- shutting-down
diff --git a/doc/cpp/wscript b/doc/cpp/wscript
index 3ccb8c7..4bef6c2 100644
--- a/doc/cpp/wscript
+++ b/doc/cpp/wscript
@@ -6,12 +6,8 @@ def build(bld):
files = [
("../../resources/pugl.svg", "sphinx/_static/pugl.svg"),
- ("../_static/custom.css", "sphinx/_static/custom.css"),
- ("../_templates/about.html", "sphinx/_templates/about.html"),
("../deployment.rst", "sphinx/deployment.rst"),
- ("../pugl.rst", "sphinx/pugl.rst"),
- ("c-reference.rst", "sphinx/c-reference.rst"),
- ("cpp-reference.rst", "sphinx/cpp-reference.rst"),
+ ("../summary.rst", "sphinx/summary.rst"),
("event-loop.rst", "sphinx/event-loop.rst"),
("events.rst", "sphinx/events.rst"),
("index.rst", "sphinx/index.rst"),
@@ -44,5 +40,5 @@ def build(bld):
bld(features="sphinx",
sphinx_source=bld.path.get_bld().make_node("sphinx"),
sphinx_output_format="singlehtml",
- sphinx_options=["-E", "-q"],
+ sphinx_options=["-E", "-q", "-t", "singlehtml"],
install_path=doc_dir + "cpp/singlehtml/")
diff --git a/doc/deployment.rst b/doc/deployment.rst
index ffbeae9..4afc51a 100644
--- a/doc/deployment.rst
+++ b/doc/deployment.rst
@@ -1,13 +1,13 @@
-##########
-Using Pugl
-##########
+#####
+Usage
+#####
-Pugl is designed for flexible deployment,
-so the exact method of building against it depends on your approach.
+*********************
+Building Against Pugl
+*********************
-When targeting systems with pkg-config_,
-packages are provided that link against the core platform library and the desired backend,
-along with any backend dependencies:
+When Pugl is installed,
+pkg-config_ packages are provided that link with the core platform library and desired backend:
- ``pugl-cairo-0``
- ``pugl-gl-0``
diff --git a/doc/pugl.rst b/doc/pugl.rst
deleted file mode 100644
index c48021b..0000000
--- a/doc/pugl.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-####
-Pugl
-####
-
-Pugl is an API for writing portable and embeddable GUIs.
-Pugl is not a toolkit or framework,
-but a minimal portability layer that sets up a drawing context and delivers events.
-
-Compared to other libraries,
-Pugl is particularly suitable for use in plugins or other loadable modules.
-There is no implicit context or static data in the library,
-so it may be statically linked and used multiple times in the same process.
-
-Pugl has a modular design that separates the core library from graphics backends.
-The core library is graphics agnostic,
-it implements platform support and depends only on standard system libraries.
-MacOS, Windows, and X11 are currently supported as platforms.
-
-Graphics backends are separate so that applications only depend on the API that they use.
-Pugl includes graphics backends for Cairo_, OpenGL_, and Vulkan_.
-It is also possible to use some other graphics API by implementing a custom backend,
-or simply accessing the native platform handle for a window.
-
-.. _Cairo: https://www.cairographics.org/
-.. _OpenGL: https://www.opengl.org/
-.. _Vulkan: https://www.khronos.org/vulkan/
generated by cgit v1.2.1 (git 2.18.0) at 2024-11-22 06:48:25 +0000