Package org.gcube.informationsystem.resourceregistry.documentation

Class RegistryDocumentationGenerator

java.lang.Object

org.gcube.informationsystem.resourceregistry.documentation.RegistryDocumentationGenerator

public class RegistryDocumentationGenerator
extends Object

Renders the live-registry documentation product distinct from the committed static docs (see the Architectural Decisions Log, "Two distinct documentation products"): the is-model bucket still comes from the classpath, since is-model is compile-time and never runtime-mutable, but the domain-model bucket comes from a SchemaSnapshot via SchemaSnapshotTypesDiscoverer, so a runtime-registered type is included exactly like a classpath-declared one.

The documentation is written in one of two ways. With the MkDocs entry point of d4science-service-docs, the pages are rendered as Markdown and built into a site by MkDocs, with a navigation listing the pages in the order of the documentation. Without it, the pages are rendered as HTML, with the sidebar of model-docs-page.html.ftl, as the Sphinx sites are. Both write the same page names (is-model.html, ...).

Writing is atomic with respect to whatever serves outputDirectory: the whole documentation set is built in a fresh temporary directory first, then swapped into place by two directory renames, so a reader of outputDirectory never observes a partially written set, and a failed build leaves the previous set in place. Neither the wiring of when this runs (on startup, on schema change) nor how outputDirectory is exposed to clients is this class's concern.

Author:

Luca Frosini (ISTI - CNR)

Constructor Summary

Constructors

Constructor	Description
RegistryDocumentationGenerator()	Creates a generator that writes the documentation as HTML.
RegistryDocumentationGenerator(File mkdocsScript, File venvDirectory)	Creates a generator that builds the documentation with MkDocs or, without a script, writes it as HTML.

Method Summary

Modifier and Type	Method	Description
void	generate(SchemaSnapshot snapshot, org.gcube.informationsystem.registry.RegistryMetadata registryMetadata, File outputDirectory)	Renders the documentation for snapshot and atomically publishes it to outputDirectory, showing the models of registryMetadata in the sidebar.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

RegistryDocumentationGenerator

public RegistryDocumentationGenerator()

Creates a generator that writes the documentation as HTML.

RegistryDocumentationGenerator

public RegistryDocumentationGenerator(File mkdocsScript,
 File venvDirectory)

Creates a generator that builds the documentation with MkDocs or, without a script, writes it as HTML.

Parameters:

mkdocsScript - the MkDocs entry point of d4science-service-docs (build_mkdocs.py), or null for HTML

venvDirectory - the directory MkDocs keeps its Python virtual environment in; unused for HTML

Method Details

generate

public void generate(SchemaSnapshot snapshot,
 org.gcube.informationsystem.registry.RegistryMetadata registryMetadata,
 File outputDirectory)
              throws Exception

Renders the documentation for snapshot and atomically publishes it to outputDirectory, showing the models of registryMetadata in the sidebar.

Parameters:

snapshot - the schema snapshot to document the domain-model bucket from

registryMetadata - the record the sidebar shows: one line per model, is-model first and the runtime model last, and the global revision count; it also names the domain-model bucket, after the domain model or, with none, after the runtime model

outputDirectory - the directory readers observe; replaced atomically on success, left untouched on failure

Throws:

Exception - if building the model knowledge, rendering the templates or the MkDocs build fails

IOException - if the temporary directory cannot be created or the swap fails