Integrating element API docs into the site

[bennypowers]

Let's use this discussion thread to concentrate ideas on documenting our element APIs on the ux.redhat.com site. We have previously discussed this on company chat, during standups, etc, so let me remind you all of some of the things we brought up and some of our goals, and let's go forward with the discussion concentrated here in this thread, so our decision making will be easy to find and act upon.

The Need

As we implement components here in the RHDS repo, we'd like to document their APIs (read: how to use them) as well. We'd like for ux.redhat.com to not only be a resource for developers on how to implement RHDS components, but also a resource for our users on how to use the components we develop.

sequenceDiagram
    autonumber
    Customer->>Designer: Identify Customer Need
    activate Designer
    Designer->>Site: Develop Design Doc
    deactivate Designer
    Site->>Developer: Implement Custom Element
    activate Developer
    Developer->>Site: Document Custom Element
    deactivate Developer
    Site->>Customer: Implement Product or Page with Custom Element

Loading

Prior Art

PatternFly Elements makes use of the custom elements manifest and associated packages to automatically generate API docs from the source code. Let's take <pfe-autocomplete> as an example. The API docs page lists the element's various APIs like properties, attributes, events, css custom properties, etc. These API docs are derived directly from the <pfe-accordion> source code and their correctness and exhaustiveness is the responsibility of the developers. The markdown+nunjucks source code for that page contains nunjucks shortcodes which are used to render the various generated docs on the page, as well as markdown content which is specific to the docs site. An example shortcode usage, to show an element's properties:

{% renderProperties %}{% endrenderProperties %}

The templates used to render those shortcodes are located in the @patternfly/pfe-tools 11ty directory.

So the pipeline for patternflyelements.org is:

sequenceDiagram
    autonumber
    participant Developer
    participant Src as Source Code
    Developer->>Src: Writes well-structured source code with inline documentation
    Src->>Manifest: Tooling Generates Manifest File
    Manifest->>11ty: Reads and Renders Manifest into Docs Page

Loading

As a straw proposal, we may use the @patternfly/pfe-tools/11ty modules to similarly generate docs page content on ux.redhat.com, and insert them into the existing component pages via the shortcodes. We may choose to also:

• Utilize njk+markdown instead of plain njk on those pages
• Improve the (hastily cobbled together) design of the docs page sections on both patternflyelements.org and on ux.redhat.com