gavo.web.examplesrender module

The renderer for VOSI examples, plus the docutils extensions provided for them.

If you have a renderer that needs custom text roles or directives, read the docstring of misctricks.RSTExtensions and add whatever roles you need below, more or less like this:

misctricks.RSTExtensions.makeTextRole("niceRole")

Only go through RSTExtensions, as these will make sure HTML postprocessing happens as required.

The reason we keep the roles here and not in the renderer modules where they’d logically belong (and where they should be documented in the renderer docstrings) is that we don’t want docutils imports all over the place.

class gavo.web.examplesrender.Examples(request, service)[source]

Bases: CustomTemplateMixin, ServiceBasedPage

A renderer for examples for service usage.

This renderer formats _example meta items in its service. Its output is XHTML compliant to VOSI examples; clients can parse it to, for instance, fill forms for service operation or display examples to users.

The examples make use of RDFa to convey semantic markup. To see what kind of semantics is contained, try http://www.w3.org/2012/pyRdfa/Overview.html and feed it the example URL of your service.

The default content of _example is ReStructuredText, and, really, not much else makes sense. An example for such a meta item can be viewed by executing gavo admin dumpDF //userconfig, in the tapexamples STREAM.

To support annotation of things within the example text, DaCHS defines several RST extensions, both interpreted text roles (used like :role-name:`content with blanks`) and custom directives (used to mark up blocks introduced by a single line like .. directive-name :: (the blanks before and after the directive name are significant).

Here’s the custom interpreted text roles:

  • dl-id: An publisher DID a service returns data for (used in datalink examples)

  • taptable: A (fully qualified) table name a TAP example query is (particularly) relevant for; in HTML, this is also a link to the table description.

  • genparam: A “generic parameter” as defined by DALI. The values of these have the form param(value), e.g., :genparam:`POS(32,4)`. Right now, not parentheses are allowed in the value. Complain if this bites you.

These are the custom directives:

  • tapquery: The query discussed in a TAP example.

Examples for how to write TAP examples are in the userconfig.rd distributed with DaCHS. Examples for Datalink examples can be found in the GAVO RDs feros/q and califa/q3.A

In addition, you can define moreExamples meta items. These point to further DALI-compliant examples document(s) and will typically be presented in a hierarchical fashion by clients. The content is either a URI to the examples document (when it starts with https?://) or a DaCHS-internal reference to a service with the examples. They should have a (short) title meta child to give clients a hint as to what the continuation is about, somewhat like this:

<meta>
        # more examples provided by the ex service in the RD rr/q
        moreExamples: rr/q#ex
        moreExamples.title: RegTAP
        # more examples provided by an external document
        moreExamples: http://ivoa.net/doc/obscore/tap-examples.xhtml
        moreExamples.title: ObsCore
</meta>
checkedRenderer = False
customTemplate = <XMLFile of '/home/msdemlei/gavo/trunk/gavo/resources/templates/examples.html'>
data_continuations(request, tag)[source]

yields dicts with title and uri keys from this service’s continuation metadata.

data_examples(request, tag)[source]

returns _Example instances from the service metadata.

data_id(request, tag)[source]

returns the htmlId attribute of the current data (an example).

data_rendered(request, tag)[source]

returns the current data (an example) as XHTML.

gavo_useDoctype = b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.1//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-2.dtd">'
classmethod isBrowseable(service)[source]

returns True if this renderer applied to service is usable using a plain web browser.

classmethod isCacheable(segments, request)[source]

should return true if the content rendered will only change when the associated RD changes.

request is a nevow request object. web.root.ArchiveService already makes sure that you only see GET request without arguments and without a user, so you do not need to check this.

name = 'examples'
noexamples(request, tag)[source]
render(request)[source]

Render a given resource. See L{IResource}’s render method.

I delegate to methods of self with the form ‘render_METHOD’ where METHOD is the HTTP that was used to make the request. Examples: render_GET, render_HEAD, render_POST, and so on. Generally you should implement those methods instead of overriding this one.

render_METHOD methods are expected to return a byte string which will be the rendered page, unless the return value is C{server.NOT_DONE_YET}, in which case it is this class’s responsibility to write the results using C{request.write(data)} and then call C{request.finish()}.

Old code that overrides render() directly is likewise expected to return a byte string or NOT_DONE_YET.

@see: L{IResource.render}

title(request, tag)[source]