Skip to content

Use AsciiDoc [example] block for all examples #1467

@jouni

Description

@jouni

AsciiDoc provides a built-in example block syntax, which we could use to mark up all examples in the documentation.

Currently, we use two different ways to mark up example.

  1. Indicated explicitly in text (with a bold "Example"), without any markup connecting the related source code snippet:2.
    Screen Shot 2022-06-10 at 17 16 43

  2. Wrapped in an open block with a custom .example class/role, which DSP recognizes and processes into feature-rich example embeds:
    Screen Shot 2022-06-10 at 17 18 54

Here’s how those could look like using the built-in syntax:

.Using the [methodname]`bindInstanceFields()` method to bind all fields in a UI class.
[example]
====
[source,java]
----
public class MyForm extends VerticalLayout {
    private TextField firstName =
            new TextField("First name");
    private TextField lastName =
            new TextField("Last name");
    private ComboBox<Gender> gender =
            new ComboBox<>("Gender");

    public MyForm() {
        Binder<Person> binder =
                new Binder<>(Person.class);
        binder.bindInstanceFields(this);
    }
}
----
====
.Title for this example
[example]
====

Description for the first source code.

[source,typescript]
----
include::../../examples/typescript/imported-example.ts[tags=*, indent=0]
----

This is the description for the second source code, with *formatting*.

[source,java]
----
include::../../examples/java/IncludedExample.java[]
----
====

One benefit of this, in addition to consistency, is that the examples would be automatically numbered, if a title is provided.

Metadata

Metadata

Assignees

No one assigned

    Labels

    DS PublisherRelated to Design System Publisher functionality rather than to the content substanceenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions