diff options
| -rw-r--r-- | doc/_static/custom.css | 95 | ||||
| -rw-r--r-- | doc/_templates/about.html | 57 | ||||
| -rw-r--r-- | doc/c/index.rst | 9 | ||||
| -rw-r--r-- | doc/c/overview.rst | 8 | ||||
| -rw-r--r-- | doc/c/reference.rst | 18 | ||||
| -rw-r--r-- | doc/c/wscript | 7 | ||||
| -rw-r--r-- | doc/conf.py.in | 79 | ||||
| -rw-r--r-- | doc/cpp/c-reference.rst | 20 | ||||
| -rw-r--r-- | doc/cpp/cpp-reference.rst | 18 | ||||
| -rw-r--r-- | doc/cpp/index.rst | 11 | ||||
| -rw-r--r-- | doc/cpp/overview.rst | 1 | ||||
| -rw-r--r-- | doc/cpp/wscript | 8 | ||||
| -rw-r--r-- | doc/deployment.rst | 16 | ||||
| -rw-r--r-- | doc/pugl.rst | 26 | ||||
| -rwxr-xr-x | scripts/dox_to_sphinx.py | 108 |
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") |