diff options
Diffstat (limited to 'giscanner/doctemplates/devdocs')
17 files changed, 510 insertions, 0 deletions
diff --git a/giscanner/doctemplates/devdocs/Gjs/_doc.tmpl b/giscanner/doctemplates/devdocs/Gjs/_doc.tmpl new file mode 100644 index 00000000..dbdb8259 --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/_doc.tmpl @@ -0,0 +1,37 @@ +<%def name="format_documentation(node)"> + % if node.version: + <p class="since-note"> + New in version ${node.version}. + ${formatter.format_inline(node, node.version_doc)} + </p> + % endif + % if node.deprecated: + <p class="deprecated-note"> + Deprecated since ${node.deprecated}. + ${formatter.format_inline(node, node.deprecated_doc)} + </p> + % endif + % if node.stability: + ## Not sure what this looks like in the wild + <p class="stability-note"> + Stability: ${node.stability}. + ${formatter.format_inline(node, node.stability_doc)} + </p> + % endif + + % if node.doc: + ${formatter.format(node, node.doc)} + % endif +</%def> + +<%def name="deprecated_class(node)"> + % if node.deprecated: + deprecated + % endif +</%def> + +<%def name="introspectable(node)"> + % if getattr(node, "introspectable", True): + ${caller.body()} + % endif +</%def> diff --git a/giscanner/doctemplates/devdocs/Gjs/_index.tmpl b/giscanner/doctemplates/devdocs/Gjs/_index.tmpl new file mode 100644 index 00000000..f3d588ae --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/_index.tmpl @@ -0,0 +1,191 @@ +<%namespace name="doc" file="_doc.tmpl"/> + +<% + ancestors = [] + if isinstance(node, ast.Class): + ancestors = formatter.get_inheritable_types(node) + + fields = getattr(node, 'fields', []) + extra_fields = [getattr(f.anonymous_node, 'fields', []) for f in fields + if f.anonymous_node is not None] + extra_fields = [field for sublist in extra_fields for field in sublist] + non_private_fields = [f for f in fields + extra_fields + if not formatter.is_private_field(node, f)] + + def get_ancestor_counts(*kinds): + counts = {} + for a in ancestors: + count = 0 + for kind in kinds: + if kind == 'fields': + count += len(non_private_fields) + else: + count += len(getattr(a, kind, [])) + if count: + counts[a] = count + return counts + + def should_render(*kinds): + has_nonempty = False + for kind in kinds: + if kind == 'fields': + if non_private_fields: + has_nonempty = True + elif getattr(node, kind, []): + has_nonempty = True + return has_nonempty or get_ancestor_counts(*kinds) +%> + +<%def name="inherited(*kinds)"> + <% counts = get_ancestor_counts(*kinds) %> + % if counts: + <% + links = ', '.join(['{} ({})'.format(formatter.format_xref(a), count) + for a, count in counts.items()]) + %> + ${formatter.format(node, '**Inherited:** ' + links)} + % endif +</%def> + +<%def name="format_function_cell(m)"> + <td class="${doc.deprecated_class(m)}"> + <a href="#${formatter.make_anchor(m)}"> + ${formatter.format_function_name(m)}<!-- no space + --></a><!-- no space + -->(${formatter.format_in_parameters(m)}) + </td> +</%def> + +% if should_render('static_methods', 'constructors', 'methods'): + <h2 id="index-methods">Methods</h2> + ${inherited('static_methods', 'constructors', 'methods')} + <% + static_methods = getattr(node, 'static_methods', []) + getattr(node, 'constructors', []) + methods = static_methods + getattr(node, 'methods', []) + %> + % if methods: + <table class="index"> + <tbody> + % for m in methods: + <%doc:introspectable node="${m}"> + <tr> + % if m in static_methods: + <td class="static-method-indicator">static</td> + % else: + <td></td> + % endif + ${format_function_cell(m)} + </tr> + </%doc:introspectable> + % endfor + </tbody> + </table> + % endif +% endif + +% if should_render('virtual_methods'): + <h2 id="index-vfuncs">Virtual methods</h2> + ${inherited('virtual_methods')} + % if getattr(node, 'virtual_methods', []): + <table> + <tbody> + % for m in node.virtual_methods: + <%doc:introspectable node="${m}"> + <tr> + ${format_function_cell(m)} + </tr> + </%doc:introspectable> + % endfor + </tbody> + </table> + % endif +% endif + +% if should_render('properties'): + <h2 id="index-properties">Properties</h2> + ${inherited('properties')} + % if getattr(node, 'properties', []): + <table> + <thead> + <tr> + <th>Name</th> + <th>Type</th> + <th>Flags</th> + </tr> + </thead> + <tbody> + % for p in node.properties: + <%doc:introspectable node="${p}"> + <tr> + <td class="${doc.deprecated_class(p)}"> + <a href="#${formatter.make_anchor(p)}">${p.name}</a> + </td> + <td>${formatter.format_type(p.type)}</td> + <td>${formatter.format_property_flags(p, abbrev=True)}</td> + </tr> + </%doc:introspectable> + % endfor + </tbody> + </table> + % endif +% endif + +% if should_render('signals'): + <h2 id="index-signals">Signals</h2> + ${inherited('signals')} + % if getattr(node, 'signals', []): + <table> + <tbody> + % for s in node.signals: + <%doc:introspectable node="${s}"> + <tr> + <td class="${doc.deprecated_class(s)}"> + <a href="#${formatter.make_anchor(s)}">${s.name}</a><!-- no space + -->(${formatter.format_in_parameters(s)}) + </td> + </tr> + </%doc:introspectable> + % endfor + </tbody> + </table> + % endif +% endif + +% if should_render('fields'): + <h2 id="index-fields">Fields</h2> + ${inherited('fields')} + % if non_private_fields: + <table> + <thead> + <tr> + <th>Name</th> + <th>Type</th> + <th>Access</th> + <th>Description</th> + </tr> + </thead> + <tbody> + % for f in non_private_fields: + <%doc:introspectable node="${f}"> + <tr> + <td class="${doc.deprecated_class(f)}"> + <span class="entry" href="#${formatter.make_anchor(f)}"> + ${f.name} + </span> + </td> + <td>${formatter.format_type(f.type)}</td> + <td>${formatter.format_property_flags(f, abbrev=True)}</td> + ## Fields almost never warrant a detailed entry, we'll just make this + ## the entry to be indexed by DevDocs + <td> + % if f.doc: + ${formatter.format_inline(node, f.doc)} + % endif + </td> + </tr> + </%doc:introspectable> + % endfor + </tbody> + </table> + % endif +% endif diff --git a/giscanner/doctemplates/devdocs/Gjs/_method.tmpl b/giscanner/doctemplates/devdocs/Gjs/_method.tmpl new file mode 100644 index 00000000..57520465 --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/_method.tmpl @@ -0,0 +1,71 @@ +<%namespace name="doc" file="_doc.tmpl"/> + +<%def name="describe_parameters(m, static=False, virtual=False)"> + <dl> + % if static: + <dt>Type:</dt> + <dd>Static</dd> + % elif virtual: + <dt>Type:</dt> + <dd>Virtual</dd> + % endif + <% + in_params = formatter.get_in_parameters(m) + out_params = formatter.get_out_parameters(m) + %> + % if in_params: + <dt>Parameters:</dt> + <dd> + <ul> + % for p in in_params: + <li> + <strong>${p.argname}</strong> + (<code>${formatter.format_type(p.type)}</code>) + % if p.doc: + — ${formatter.format_inline(m, p.doc)} + % endif + </li> + % endfor + </ul> + </dd> + % endif + % if out_params: + <dt>Returns:</dt> + <dd> + <ul> + % for p in out_params: + <li> + % if len(out_params) > 1: + <strong>${p.argname}</strong> + % endif + (<code>${formatter.format_type(p.type)}</code>) + % if p.doc: + — ${formatter.format_inline(m, p.doc)} + % endif + </li> + % endfor + </ul> + </dd> + % endif + % if m.throws: + <dt>Throws exception:</dt> + <dd>Yes</dd> + % endif + </dl> +</%def> + +<%def name="method(m, static=False, virtual=False)"> + <%doc:introspectable node="${m}"> + <% invocation = ", ".join(map(lambda p: p.argname, m.parameters)) %> + + <h3> + <span class="entry ${get_node_kind(m)} ${doc.deprecated_class(m)}" + id="${formatter.make_anchor(m)}"> + ${formatter.format_function_name(m)}<!-- no space + --></span><!-- no space + -->(${formatter.format_in_parameters(m)}) + </h3> + ${describe_parameters(m, static, virtual)} + ${doc.format_documentation(m)} + </%doc:introspectable> +</%def> diff --git a/giscanner/doctemplates/devdocs/Gjs/_methods.tmpl b/giscanner/doctemplates/devdocs/Gjs/_methods.tmpl new file mode 100644 index 00000000..e876cd68 --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/_methods.tmpl @@ -0,0 +1,4 @@ +<%namespace name="method" file="_method.tmpl"/> +% for m in getattr(node, 'methods', []): + ${method.method(m)} +% endfor diff --git a/giscanner/doctemplates/devdocs/Gjs/_properties.tmpl b/giscanner/doctemplates/devdocs/Gjs/_properties.tmpl new file mode 100644 index 00000000..a7054727 --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/_properties.tmpl @@ -0,0 +1,38 @@ +<%namespace name="doc" file="_doc.tmpl"/> +<%! + def dash_to_underscore(string): + return '_'.join(string.split('-')) + + def dash_to_camel(string): + words = string.split('-') + return ''.join([words[0]] + [word.title() for word in words[1:]]) +%> +% if getattr(node, 'properties', []): + <h2>Property Details</h2> + % for p in node.properties: + <%doc:introspectable node="${p}"> + <h3 class="entry property ${doc.deprecated_class(p)}" + id="${formatter.make_anchor(p)}"> + ${p.name | dash_to_underscore} + </h3> + <dl> + % if p.name.lower() != p.name: + <dt>Names</dt> + <dd> + <code>${p.name}</code>, <code>${p.name | dash_to_underscore}</code>, + <code>${p.name | dash_to_camel}</code> + </dd> + % endif + <dt>Type</dt> + <dd><code>${formatter.format_type(p.type)}</code></dd> + ##<dt>Default value</dt> + ##<dd>Not currently stored in GIR</dd> + <dt>Flags</dt> + <dd>${formatter.format_property_flags(p)}</dd> + </dl> + % if p.doc: + ${doc.format_documentation(p)} + % endif + </%doc:introspectable> + % endfor +% endif diff --git a/giscanner/doctemplates/devdocs/Gjs/_signals.tmpl b/giscanner/doctemplates/devdocs/Gjs/_signals.tmpl new file mode 100644 index 00000000..cda46bd5 --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/_signals.tmpl @@ -0,0 +1,22 @@ +<%namespace name="doc" file="_doc.tmpl"/> +<%namespace name="method" file="_method.tmpl"/> +% if getattr(node, 'signals', []): + <h2>Signal Details</h2> + % for s in node.signals: + <%doc:introspectable node="${s}"> + <h3> + <span class="entry signal ${doc.deprecated_class(s)}" + id="${formatter.make_anchor(s)}"> + ${s.name}<!-- no space + --></span><!-- + -->(${formatter.format_in_parameters(s)}) + </h3> + <dl> + <dt>Flags</dt> + <dd>${formatter.format_signal_flags(s)}</dd> + ${method.describe_parameters(s)} + </dl> + ${doc.format_documentation(s)} + </%doc:introspectable> + % endfor +% endif diff --git a/giscanner/doctemplates/devdocs/Gjs/_staticmethods.tmpl b/giscanner/doctemplates/devdocs/Gjs/_staticmethods.tmpl new file mode 100644 index 00000000..dcd542e1 --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/_staticmethods.tmpl @@ -0,0 +1,4 @@ +<%namespace name="method" file="_method.tmpl"/> +% for m in getattr(node, 'static_methods', []) + getattr(node, 'constructors', []): + ${method.method(m, static=True)} +% endfor diff --git a/giscanner/doctemplates/devdocs/Gjs/_vfuncs.tmpl b/giscanner/doctemplates/devdocs/Gjs/_vfuncs.tmpl new file mode 100644 index 00000000..2966ede4 --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/_vfuncs.tmpl @@ -0,0 +1,6 @@ +<%namespace name="method" file="_method.tmpl"/> +% if getattr(node, 'virtual_methods', []): + % for m in node.virtual_methods: + ${method.method(m, virtual=True)} + % endfor +% endif diff --git a/giscanner/doctemplates/devdocs/Gjs/base.tmpl b/giscanner/doctemplates/devdocs/Gjs/base.tmpl new file mode 100644 index 00000000..913fa0cc --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/base.tmpl @@ -0,0 +1,21 @@ +<%namespace name="doc" file="_doc.tmpl"/> +<html> +<body> + <section> + <h1 class="${page_kind} ${doc.deprecated_class(node)} ${self.extra_class()}"> + ${formatter.format_page_name(node)} + </h1> + <%include file="_index.tmpl"/> + <h2>Details</h2> + ${doc.format_documentation(node)} + <%include file="_staticmethods.tmpl"/> + <%include file="_methods.tmpl"/> + <%include file="_vfuncs.tmpl"/> + <%include file="_signals.tmpl"/> + <%include file="_properties.tmpl"/> + ${self.body()} + </section> +</body> +</html> + +<%def name="extra_class()"/> diff --git a/giscanner/doctemplates/devdocs/Gjs/callback.tmpl b/giscanner/doctemplates/devdocs/Gjs/callback.tmpl new file mode 100644 index 00000000..2795ee3c --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/callback.tmpl @@ -0,0 +1,3 @@ +<%namespace name="method" file="_method.tmpl"/> +<%inherit file="base.tmpl"/> +${method.describe_parameters(node)} diff --git a/giscanner/doctemplates/devdocs/Gjs/class.tmpl b/giscanner/doctemplates/devdocs/Gjs/class.tmpl new file mode 100644 index 00000000..9d2b5238 --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/class.tmpl @@ -0,0 +1 @@ +<%inherit file="base.tmpl"/> diff --git a/giscanner/doctemplates/devdocs/Gjs/default.tmpl b/giscanner/doctemplates/devdocs/Gjs/default.tmpl new file mode 100644 index 00000000..4b08adff --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/default.tmpl @@ -0,0 +1,34 @@ +<%inherit file="base.tmpl"/> +% if isinstance(node, ast.Constant): + <dl> + <dt>Value</dt> + <dd> + <code data-mime="application/javascript"><!-- + -->${formatter.format_value(node)}</code> + </dd> + </dl> +% endif +% if isinstance(node, ast.Alias): + <dl> + <dt>Equivalent Type</dt> + <dd> + <code data-mime="application/javascript"> + % if node.target.target_fundamental: + ${formatter.format_fundamental_type(node.target.target_fundamental)} + % else: + ${node.target.target_giname} + % endif + </code> + </dd> + </dl> +% endif + +## This should belong in get_node_kind(), but we don't want to change the way +## all the other templates work. +<%def name="extra_class()"> + % if isinstance(node, ast.Constant): + constant + % elif isinstance(node, ast.Alias): + alias + % endif +</%def> diff --git a/giscanner/doctemplates/devdocs/Gjs/enum.tmpl b/giscanner/doctemplates/devdocs/Gjs/enum.tmpl new file mode 100644 index 00000000..a66cbefa --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/enum.tmpl @@ -0,0 +1,16 @@ +<%inherit file="base.tmpl"/> +<ul> +% for m in node.members: + <li> + <code> + <span class="entry" id="${formatter.make_anchor(m)}"> + ${m.name.upper()} + </span> + = ${m.value} + </code> + % if m.doc: + — ${formatter.format_inline(node, m.doc)} + % endif + </li> +% endfor +</ul> diff --git a/giscanner/doctemplates/devdocs/Gjs/function.tmpl b/giscanner/doctemplates/devdocs/Gjs/function.tmpl new file mode 100644 index 00000000..2795ee3c --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/function.tmpl @@ -0,0 +1,3 @@ +<%namespace name="method" file="_method.tmpl"/> +<%inherit file="base.tmpl"/> +${method.describe_parameters(node)} diff --git a/giscanner/doctemplates/devdocs/Gjs/interface.tmpl b/giscanner/doctemplates/devdocs/Gjs/interface.tmpl new file mode 100644 index 00000000..9d2b5238 --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/interface.tmpl @@ -0,0 +1 @@ +<%inherit file="base.tmpl"/> diff --git a/giscanner/doctemplates/devdocs/Gjs/method.tmpl b/giscanner/doctemplates/devdocs/Gjs/method.tmpl new file mode 100644 index 00000000..2c997c09 --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/method.tmpl @@ -0,0 +1 @@ +<%inherit file="function.tmpl"/>
\ No newline at end of file diff --git a/giscanner/doctemplates/devdocs/Gjs/namespace.tmpl b/giscanner/doctemplates/devdocs/Gjs/namespace.tmpl new file mode 100644 index 00000000..8f5a4e7e --- /dev/null +++ b/giscanner/doctemplates/devdocs/Gjs/namespace.tmpl @@ -0,0 +1,57 @@ +<%def name="get_types(n, types)"> + <% nodes = [] %> + % for a in n.values(): + % if isinstance(a, types): + % if formatter.should_render_node(a): + <% nodes.append(a) %> + % endif + % endif + % endfor + <% return nodes %> +</%def> + +<%def name="render_list(nodes)"> + <ul> + % for a in nodes: + <li>${formatter.format_inline(a, formatter.format_xref(a))}</li> + % endfor + </ul> +</%def> + +<html> +<body> + <section> + <h1 class="namespace">${node.name}</h1> + </section> + + <% nodes = get_types(node, (ast.Class, ast.Interface)) %> + % if len(nodes) > 0: + <h1>Classes</h1> + ${render_list(nodes)} + % endif + + <% nodes = get_types(node, (ast.Enum)) %> + % if len(nodes) > 0: + <h1>Enums</h1> + ${render_list(nodes)} + % endif + + <% nodes = get_types(node, (ast.Function)) %> + % if len(nodes) > 0: + <h1>Functions</h1> + ${render_list(nodes)} + % endif + + <% nodes = get_types(node, (ast.Constant)) %> + % if len(nodes) > 0: + <h1>Constants</h1> + ${render_list(nodes)} + % endif + + <% nodes = get_types(node, (ast.Property)) %> + % if len(nodes) > 0: + <h1>Properties</h1> + ${render_list(nodes)} + % endif +</body> +</html> |