Simplify documentation structure and use LV2 theme

15 files changed, 120 insertions, 361 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/
diff --git a/scripts/dox_to_sphinx.py b/scripts/dox_to_sphinx.py
index b4eee9f..b88a484 100755
--- a/scripts/dox_to_sphinx.py
+++ b/scripts/dox_to_sphinx.py
@@ -238,7 +238,7 @@ def heading(text, level):
     chars = ("#", "*", "=", "-", "^", '"')
     line = chars[level] * len(text)
 
-    return "%s\n%s\n%s\n\n" % (line if level < 3 else "", text, line)
+    return "%s%s\n%s\n\n" % (line + "\n" if level < 3 else "", text, line)
 
 
 def dox_to_rst(index, lang, node):
@@ -257,6 +257,12 @@ def dox_to_rst(index, lang, node):
 
         return " " + markup.strip()
 
+    if node.tag == "lsquo":
+        return "‘"
+
+    if node.tag == "rsquo":
+        return "’"
+
     if node.tag == "computeroutput":
         assert len(node) == 0
         return "``%s``" % node.text
@@ -332,7 +338,7 @@ def description_markup(index, lang, node):
     assert not (node.tag == "briefdescription" and len(node) > 1)
     assert len(node.text.strip()) == 0
 
-    return "".join([dox_to_rst(index, lang, child) for child in node])
+    return "".join([dox_to_rst(index, lang, child) for child in node]).strip()
 
 
 def set_descriptions(index, lang, definition, record):
@@ -454,6 +460,9 @@ def read_definition_doc(index, lang, root):
                             name,
                         )
 
+            elif kind == "variable":
+                record["definition"] = member.find("definition").text
+
 
 def declaration_string(record):
     """
@@ -474,6 +483,11 @@ def declaration_string(record):
         result += record["prototype"]
     elif kind == "typedef":
         result += record["definition"]
+    elif kind == "variable":
+        if "parent" in record:
+            result += "%s %s" % (record["type"], local_name(record["name"]))
+        else:
+            result += record["definition"]
     elif "type" in record:
         result += "%s %s" % (record["type"], local_name(record["name"]))
     else:
@@ -497,9 +511,9 @@ def document_markup(index, lang, record):
     markup += ".. %s:: %s\n" % (role, declaration_string(record))
 
     # Write main description blurb
-    markup += "\n"
-    markup += indent(record["briefdescription"], 1)
-    markup += indent(record["detaileddescription"], 1)
+    markup += "\n" + indent(record["briefdescription"] + "\n", 1)
+    if len(record["detaileddescription"]) > 0:
+        markup += "\n" + indent(record["detaileddescription"], 1) + "\n"
 
     assert (
         kind in ["class", "enum", "namespace", "struct", "union"]
@@ -510,7 +524,7 @@ def document_markup(index, lang, record):
     child_indent = 0 if kind == "namespace" else 1
 
     # Write inline children if applicable
-    markup += "\n"
+    markup += "\n" if "children" in record else ""
     for child_id in record.get("children", []):
         child_record = index[child_id]
         child_role = sphinx_role(child_record, lang)
@@ -524,7 +538,6 @@ def document_markup(index, lang, record):
         markup += indent(child_header, child_indent)
         markup += indent(child_record["briefdescription"], child_indent + 1)
         markup += indent(child_record["detaileddescription"], child_indent + 1)
-        markup += "\n"
 
     return markup
 
@@ -535,28 +548,7 @@ def symbol_filename(name):
     return name.replace("::", "__")
 
 
-def emit_symbols(index, lang, symbol_dir, force):
-    """Write a description file for every symbol documented in the index."""
-
-    for record in index.values():
-        if (
-            record["kind"] in ["group", "namespace"]
-            or "parent" in record
-            and index[record["parent"]]["kind"] != "group"
-        ):
-            continue
-
-        name = record["name"]
-        filename = os.path.join(symbol_dir, symbol_filename("%s.rst" % name))
-        if not force and os.path.exists(filename):
-            raise FileExistsError("File already exists: '%s'" % filename)
-
-        with open(filename, "w") as rst:
-            rst.write(heading(local_name(name), 3))
-            rst.write(document_markup(index, lang, record))
-
-
-def emit_groups(index, output_dir, symbol_dir_name, force):
+def emit_groups(index, lang, output_dir, force):
     """Write a description file for every group documented in the index."""
 
     for record in index.values():
@@ -569,40 +561,38 @@ def emit_groups(index, output_dir, symbol_dir_name, force):
             raise FileExistsError("File already exists: '%s'" % filename)
 
         with open(filename, "w") as rst:
-            rst.write(heading(record["title"], 2))
+            rst.write(heading(record["title"], 1))
 
             # Get all child group and symbol names
-            group_names = []
-            symbol_names = []
+            child_groups = {}
+            child_symbols = {}
             for child_id in record["children"]:
                 child = index[child_id]
                 if child["kind"] == "group":
-                    group_names += [child["name"]]
+                    child_groups[child["name"]] = child
                 else:
-                    symbol_names += [child["name"]]
+                    child_symbols[child["name"]] = child
 
             # Emit description (document body)
-            rst.write(record["briefdescription"] + "\n\n")
-            rst.write(record["detaileddescription"] + "\n\n")
-
-            # Emit TOC
-            rst.write(".. toctree::\n")
+            if len(record["briefdescription"]) > 0:
+                rst.write(record["briefdescription"] + "\n\n")
+            if len(record["detaileddescription"]) > 0:
+                rst.write(record["detaileddescription"] + "\n\n")
 
-            # Emit groups at the top of the TOC
-            for group_name in group_names:
-                rst.write("\n" + indent(group_name, 1))
+            if len(child_groups) > 0:
+                # Emit TOC for child groups
+                rst.write(".. toctree::\n\n")
+                for name, group in child_groups.items():
+                    rst.write(indent(group["name"], 1) + "\n")
 
             # Emit symbols in sorted order
-            for symbol_name in sorted(symbol_names):
-                path = "/".join(
-                    [symbol_dir_name, symbol_filename(symbol_name)]
-                )
-                rst.write("\n" + indent(path, 1))
+            for name, symbol in child_symbols.items():
+                rst.write("\n")
+                rst.write(document_markup(index, lang, symbol))
+                rst.write("\n")
 
-            rst.write("\n")
 
-
-def run(index_xml_path, output_dir, symbol_dir_name, language, force):
+def run(index_xml_path, output_dir, language, force):
     """Write a directory of Sphinx files from a Doxygen XML directory."""
 
     # Build skeleton index from index.xml
@@ -624,11 +614,14 @@ def run(index_xml_path, output_dir, symbol_dir_name, language, force):
     for root in definition_docs:
         read_definition_doc(index, language, root)
 
+    # Create output directory
+    try:
+        os.makedirs(output_dir)
+    except OSError:
+        pass
+
     # Emit output files
-    symbol_dir = os.path.join(output_dir, symbol_dir_name)
-    os.makedirs(symbol_dir, exist_ok=True)
-    emit_symbols(index, language, symbol_dir, force)
-    emit_groups(index, output_dir, symbol_dir_name, force)
+    emit_groups(index, language, output_dir, force)
 
 
 if __name__ == "__main__":
@@ -653,13 +646,6 @@ if __name__ == "__main__":
         help="language domain for output",
     )
 
-    ap.add_argument(
-        "-s",
-        "--symbol-dir-name",
-        default="symbols",
-        help="name for subdirectory of symbol documentation files",
-    )
-
     ap.add_argument("index_xml_path", help="path index.xml from Doxygen")
     ap.add_argument("output_dir", help="output directory")