Uploaded image for project: 'Quarkus Documentation'
  1. Quarkus Documentation
  2. QDOCS-171

Fix code snippets of upstream-first content in downstream repo

XMLWordPrintable

    • Quarkus Upstream Docs Sprint 3, Quarkus Upstream Docs Sprint 4, Quarkus Upstream Docs Sprint 5

      Fix this problem:

      Raw upstream AsciiDoc source files imported into the downstream link will contain code snippets with attributes and includes that will not work in quarkus downstream docs.

      Why? 

      As per limitation 8 in this initial research doc. 

      We don't have this feature downstream:

       

      So some markup changes and rewriting needs to be done, as per the current downstream guides (see getting started as an example):

       

      Example of unsupported code attributes downstream:

      [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]

       

      [source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]

      Scope of this PR

      • Fix code snippets in the first batch of security topics and ensure that they render as expected on Jenkins and then PV2.
      • Fix tagging on commented out sections of code snippets to ensure distinction between comments and actual code is more visible, for example, comments appear in a different colour. For more information, see Spot checks doc  (Note as this fix is lower prio, if, after investigation, it might require a lot of time, consider creating a separate Jira and adding to backlog instead). 

      Later (outside scope of this JIRA)

      1. Needs new Jira to investigate a dynamic approach to automating the conversion downstream.
        Work with CCS tooling to have a similar tab feature supported in our stylesheet in downstream docs.

        1. image-2023-02-16-10-24-11-994.png
          78 kB
          Michelle Purcell
        2. image-2023-02-27-13-41-04-197.png
          59 kB
          Michal Maléř

              mmaler@redhat.com Michal Maléř
              mpurcell@redhat.com Michelle Purcell
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Created:
                Updated:
                Resolved: