Template block macro (handlebars) #671

osfameron · 2023-04-24T12:37:22Z

See https://docs-staging.couchbase.com/home/contribute/extensions-template.html for a built demo of this.
(@mojavelinux I'll ping you the password for this separately)

This extension enables a [template] block which formats a specified .json file against a .hbs Handlebars template.

[template,example$some-data.json]
--
include::partial$templates/test.hbs[]

or, e.g:

{{#each items}}
* {{name}}
{{/each}}
--

See https://issues.couchbase.com/browse/DOC-10720 for a motivating example (metrics).

Other use-cases keep coming up:

OpenAPI to configuration schema generation, (currently done dynamically at e.g. https://docs.couchbase.com/sync-gateway/current/configuration-schema-database.html#_database )
Jira report -> release notes generation

etc.
`

This extension enables a `[template]` block which formats a specified .json file against a .hbs Handlebars template. ``` [template,example$some-data.json] -- include::partial$templates/test.hbs[] or, e.g: {{#each items}} * {{name}} {{/each}} -- ``` See https://issues.couchbase.com/browse/DOC-10720 for a motivating example (metrics). Other use-cases keep coming up: * OpenAPI to configuration schema generation, (currently done dynamically at e.g. https://docs.couchbase.com/sync-gateway/current/configuration-schema-database.html#_database ) * Jira report -> release notes generation etc. `

malarky

Hi @osfameron, as discussed, this looks like it definitely fulfils the primary requirement, which was to replace the current metrics reference tables with the JSON delivered from the builds. It also gives us a good starting point to be able to improve the docs with (for example) improved styling, version tags, deprecation notices, etc.

home/modules/contribute/examples/kv-metrics.json

leeming · 2023-04-26T07:53:00Z

home/modules/contribute/pages/extensions-template.adoc

@@ -0,0 +1,44 @@
+= Demo of template extension


(Minor) Niggle around the name "template", but that may just be the lack of familiarity with the tooling. Seems an overloaded term

lib/template-block.js

leeming

Looks good overall as it seems to hit the functional ask. Some minor points, but not worth holding up progress for them, more FYI/opinion.

mojavelinux · 2023-04-26T20:11:46Z

lib/template-block.js

+
+    self.named('template')
+    self.positionalAttributes('resourceId')
+    self.onContext(['listing', 'open', 'paragraph'])


I would recommend only using the open block (and maybe the paragraph). That's because the output becomes an open block. If it were used on a listing as is, you'd be changing the content model, which is not friendly to tooling. This could be resolved by detecting the original content module (by looking for cloaked-context), but it would be best to make that a separate enhancement.

That's fine, I've previously used only open (for the "Markdown-ish" block) but I think I copied this from a doc/example in case it was best practice... will revert to just open 👍

mojavelinux · 2023-04-26T20:19:08Z

lib/template-block.js

+        return self.createOpenBlock(parent, output)
+      }
+      else {
+        return self.createOpenBlock(parent, `Data file ${attributes.resourceId} not resolved`)


It would be best to log an message here. Refer to these pages to learn how:

https://docs.asciidoctor.org/asciidoctor/latest/extensions/logging/

https://docs.asciidoctor.org/asciidoctor.js/latest/processor/logging-api/

@mojavelinux I'm confused on how to include Asciidoctor::Logging in JS rather than Ruby?

The second link for JS appears to be for choosing the overall Logger for the whole processing, as opposed to calling the logger from an extension.

Yikes, I found this on the internets, but feels like there must be a simpler way?

const Opal = global.Opal const loggerManager = Opal.module(null, 'Asciidoctor').LoggerManager const logger = loggerManager.getLogger()

Well, I've pushed a commit with that in meantime, but look forward to pointers to improve!

I looked into it and the use of the Logging module in extensions is not yet well supported yet in Asciidoctor.js.

Here's the low-level JavaScript that would mix in the module:

self.$singleton_class().$include(global.Opal.Asciidoctor.Logging)

However, that won't give you access to getLogger() and createLogMessage() because this doesn't mix in Asciidoctor.js' porcelain interface.

It's probably best to use the Logging module directly:

const Logging = global.Opal.Asciidoctor.Logging ... Logging.getLogger().error('message') // or Logging.getLogger().error( Logging.createLogMessage('message', { source_location: parent.getDocument().getReader().$cursor_at_mark() }) )

It's also possible to get the logger from the parent or reader:

parent.getLogger() reader.getLogger()

That will give you the ability to log a basic message. However, in order to use createLogMessage to add context, you still need to use the Logging module.

mojavelinux · 2023-04-26T20:20:26Z

In general, this seems sound to me. I left some comments in addition to the ones by Andrew. If those could be addressed, I'd give this a 👍.

Dan points out this syntax (though sounds like in future there may be a way natively exposed via Asciidoctor.js) We might also want to use Logging.createLogMessage, e.g. Logging.createLogMessage('message', { source_location: parent.getDocument().getReader().$cursor_at_mark() })

First cut - the data files are currently placeholders, and will be updated by Dev once reviewed. This build relies on feature in couchbase/docs-site#671

e.g. instead of attempting to do it in Handlebars

* Now linked and ready for POC in Mobile (TODO remaining for additionalProperties, and will need iteration) * markdown-block now uses a library (as the markdown in the new OpenAPI spec benefits from this)

Though openapi spec defaults to yaml, yaml's pathological flexibility with references means that, even with `redocly bundle --defererenced` the definition of schemas is spread across the file. Outputting as JSON means that you get a flatter (and much larger file). The advantage is that it's easier to fillet (e.g. remove all the bits that aren't in the database schema) to make it a smaller example file for docs-site.

leeming · 2023-05-12T08:10:05Z

home/modules/contribute/examples/helpers/each-openapi.js

+    // we format it depending on its type (e.g. surrounding it in quotes etc.)
+
+    function format_type (node) {
+        if (node.type == 'object') return


(minor?) My JS is rusty (some Typescript tho), but doesn't JS use triple === for boolean truthy, similar to PHP/Perl where strings are booleans, numbers and everything else

Both work, but you are strongly advised to use ===. The only time you should use == is when comparing against null (since that catches undefined too).

osfameron · 2023-05-12T08:24:48Z

The each-openapi functionality is used in couchbase/docs-sync-gateway#738 if more context is needed

sarahlwelton · 2023-05-15T17:55:55Z

home/modules/contribute/examples/helpers/each-openapi.js

+            node.example ??
+            node.default ??
+            types[node.type]?.fallback ??
+            node.type ??


Just curious why we're not trying to return the type of node first?

The logic is:

an example (e.g. "An interesting/illuminating value that could go here")

the default (e.g. 1)

the fallback (e.g. true for boolean values)

the plain type (e.g. string)

(unknown)

As most nodes have a type (in theory all of them but my JSON Schema parsing is a bit basic for additionalProperties handling) then that's in some sense the least interesting thing that we can say about them.

* DOC-10720: Metrics Reference First cut - the data files are currently placeholders, and will be updated by Dev once reviewed. This build relies on feature in couchbase/docs-site#671 * DOC-10720: Metrics Reference update via Chris Malarky. This updates 5 of the components, and reverts the rest to their previous format.

osfameron requested review from leeming and a team April 24, 2023 12:37

osfameron self-assigned this Apr 24, 2023

osfameron requested review from malarky and tonyjhillman April 24, 2023 12:40

malarky approved these changes Apr 24, 2023

View reviewed changes

leeming reviewed Apr 26, 2023

View reviewed changes

home/modules/contribute/examples/kv-metrics.json Show resolved Hide resolved

leeming reviewed Apr 26, 2023

View reviewed changes

lib/template-block.js Show resolved Hide resolved

leeming approved these changes Apr 26, 2023

View reviewed changes

mojavelinux reviewed Apr 26, 2023

View reviewed changes

osfameron added 2 commits April 27, 2023 12:44

Support YAML, comments, code-review updates

df65985

osfameron added a commit to osfameron/docs-server that referenced this pull request May 2, 2023

DOC-10720: Metrics Reference

cbc0142

First cut - the data files are currently placeholders, and will be updated by Dev once reviewed. This build relies on feature in couchbase/docs-site#671

osfameron mentioned this pull request May 2, 2023

DOC-10720: Metrics Reference couchbase/docs-server#3155

Merged

osfameron added 2 commits May 2, 2023 13:48

Refactor and reindent

56bf3a1

Partials, helpers, cleanup

88a2906

osfameron force-pushed the hbs-templating branch from e6fdc06 to 88a2906 Compare May 4, 2023 14:21

osfameron added 6 commits May 4, 2023 18:07

Improved openapi iterator

0168ae3

Move OpenAPI config gen to JS

aaaaa63

e.g. instead of attempting to do it in Handlebars

Fix each-openapi templating

a7e482d

* Now linked and ready for POC in Mobile (TODO remaining for additionalProperties, and will need iteration) * markdown-block now uses a library (as the markdown in the new OpenAPI spec benefits from this)

Filter deprecated

bd8428a

refactor

274013c

osfameron requested review from RichardSmedley, simon-dew and tom-rosewell May 12, 2023 07:57

osfameron requested a review from sarahlwelton May 12, 2023 07:57

Refactor and fix each-openapi

79d4a07

osfameron mentioned this pull request May 12, 2023

Configuration json UI couchbase/docs-sync-gateway#738

Merged

leeming reviewed May 12, 2023

View reviewed changes

Good things come in 3s

da2336c

sarahlwelton reviewed May 15, 2023

View reviewed changes

update comment

da013f7

osfameron merged commit a29545c into couchbase:master May 16, 2023

osfameron deleted the hbs-templating branch May 16, 2023 07:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Template block macro (handlebars) #671

Template block macro (handlebars) #671

osfameron commented Apr 24, 2023

malarky left a comment

leeming Apr 26, 2023

leeming left a comment

mojavelinux Apr 26, 2023

osfameron Apr 27, 2023

mojavelinux Apr 26, 2023

osfameron Apr 27, 2023

osfameron Apr 27, 2023

osfameron Apr 27, 2023

mojavelinux Apr 30, 2023

mojavelinux commented Apr 26, 2023

leeming May 12, 2023

mojavelinux May 12, 2023

osfameron commented May 12, 2023

sarahlwelton May 15, 2023

osfameron May 16, 2023

Template block macro (handlebars) #671

Template block macro (handlebars) #671

Conversation

osfameron commented Apr 24, 2023

malarky left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

leeming left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mojavelinux commented Apr 26, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

osfameron commented May 12, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment