Uploaded image for project: 'Debezium'
  1. Debezium
  2. DBZ-5576

Improve documentation editing experience by setting attributes for the preview

    XMLWordPrintable

Details

    Description

      When looking at the Debezium docs, I see that some attributes are defined in the playbook, and some of them are defined in the Antora component descriptor. When opening just the docs in the IDE, the IntelliJ plugin will mark all undefined attributes as a warning as it suspects that there might be a typo in the attribute name, and the preview will render without the value. 
       
      Examples: 

      • {jira-url}
      • {prodname}
      • {product}

      To make the plugin aware that those are written correctly and maybe even provide values for the preview, there are different options. 
      Two things I assumed you didn't want to do: 

      • Place those values in the antora.yml file - I assume you didn't want to do this as the JIRA URL, and prodname should be defined in one place (the playbook) and not in every branch (in the component version descriptor).
      • IntelliJ supports opening multiple Git repositories in one project. This way the IDE will "see" the playbook, and will use all attributes defined there. While this prevents duplication, I consider it too complicated to set up for a drive-by user. 
        There is a third option using an ".asciidoctorconfig" file that contains "hints" and is only used for the preview in IntelliJ, see https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html for more information.
         

      Placing such a ".asciidoctorconfig" file in the "documentation" folder with the following contents ...
       

      :prodname: Debezium
      :jira-url: 'https://issues.redhat.com'
      :product!:

       
      ... would do the following: 

      • Render the preview with "Debezium" instead of "{prodname}".
      • Have links to JIRA clickable in the preview.
      • Avoids warnings in the editor about an undefined attribute prodname, jira-url and product. 

      As an alternative, if you want to keep the "{prodname}" in the preview to show in the preview that there is no hardcoded name of Debezium, the file could contain ":prodname!:" to indicate to the IDE that this attribute is explicitly unset, and it will then stop complaining about a not defined attribute. 

      After a previous discussion with ccranfor@redhat.com this issue explores the ".asciidoctorconfig" option as those values should just be set for the preview in the IDE, and should now be used for building the docs upstream nor downstream.

      I'll create a PR for this shortly.

      Attachments

        Activity

          People

            ccranfor@redhat.com Chris Cranford
            aschwart@redhat.com Alexander Schwartz
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved: