Better documentation of template macros, and their relationship to Sass patterns

[mirisuzanne]

Problems with the current implementation:

• It's only possibly to render each macro with one set of arguments
• It's not possible to render a macro with a caller
• The link between macros and Sass blocks is 1-to-1

[mirisuzanne]

Based on OddBird discussion:

• In documenting a pattern, the macro is central and the styles are incidental.
• Herman is right to document brand abstracts from the Sass side, but component patterns are better documented from the template language.
• The output should show the macro name, description, parameters (including a caller), and several rendered examples.

[mirisuzanne]

After further discussion, sounds like it may be easier to add robust macro documentation as an extension on the @example annotation that already exists. Here's my rough understanding, but maybe @davisagli or @jgerigmeyer wants to expand on it (or take assignment of the issue)?

• we should be able to provide multiple examples, with different arbitrary arguments and use of callers.
• examples should be rendered if they are in an explicitly-stated language that we can compile to HTML. In other words, sass/css/js examples can be output as highlighted code-blocks. HTML should be output directly (along side a code block), and Jinja/Nunjucks macros should be compiled and rendered.

[davisagli]

I've got an implementation of this started in the rendered-nunjucks-examples branch (https://github.com/oddbird/sassdoc-theme-herman/compare/rendered-nunjucks-examples)

That adds special handling for the normal sassdoc @example annotation so that if the example language is "njk", it will be displayed both as source and as a rendered nunjucks template.

For example this:

// Test Macro
// ----------
// This is a test.
/// @example njk - Basic usage:
///  {% import 'macros.j2' as macros %}
///  {{ macros.mymacro(1, 2) }}
/// @group test
[data-mymacro] {}

shows up like this:

Maybe we also want to make it possible to document a macro without attaching that documentation to a particular Sass block, but I think that's outside the scope of this ticket. This should already handle multiple examples attached to the same block and multiple blocks with examples of the same macro.

Does this change what we want to do with the @macro annotation? I think we probably should remove its handling of macroname_data to provide example input, to avoid having two ways to do the same thing. But we probably want to at least keep the handling of macroname_doc so that macros can include some inline documentation.

We might want a way to configure a custom getNunjucksEnv function, so that custom filters can be provided.

[carljm]

(Created a PR from that branch just for code-review purposes, though it turned out then that I didn't have any line-by-line code-review comments :-) Looks great!)

The main improvements that come to mind would be a) allowing passing in a customized nunjucks env, as you mentioned, and b) reducing the duplicated getNunjucksEnv code between the @macro, @icons, and @example annotations.

I agree with you that macroname_data can go away, given this better approach. I wonder whether macroname_doc can go away too: it seems like template-author-oriented inline macro documentation is more readable if done in a nunjucks comment, and designer-oriented documentation can probably be handled entirely via @example?

[jgerigmeyer]

I went ahead and removed macroname_data. I left macroname_doc, but it looks like it's not being called in the templates at all yet. I also cleaned up some of the code duplication. I did not allow passing in a custom nunjucks env, but that can be a new feature if @mirisuzanne wants to get this merged now.

[mirisuzanne]

There is a proposed syntax for template-driven documentation in templates/items/preview.macros.j2 using the same @annotation's available in SassDoc.

{#
  Font Specimen
  -------------
  Display all font-family specimens,
  including multiple variants.

  @group font-specimen

  @prop {String} name -
    Title for the font-family being displayed.
  @prop {Dict} data -
    All the available data on a given font,
    derived from the Sass JSON export.
  @prop {Dict} args -
    Arbitrary arguments passes along
    in the font-specimen call
    (currently only `show` and `key` are supported).
#}