vaadin / docs

Official documentation for Vaadin and Hilla.
https://vaadin.com/docs
Other
29 stars 195 forks source link

Use AsciiDoc `[example]` block for all examples #1467

Open jouni opened 2 years ago

jouni commented 2 years ago

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.

jouni commented 2 years ago

Note, that we would need to update DSP to handle the built-in AsciiDoc syntax similarly as we now process the custom .example class/role.