Uploaded image for project: 'Product Roadmaps'
  1. Product Roadmaps
  2. MMF-1668

Include documentation from on-board plugins in Embedded docs

    XMLWordPrintable

    Details

    • Type: MMF
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Labels:

      Description

      Why

      We'd like to include the analyzer documentation in the embedded docs, but currently any languages documentation we add will suffer from being static. That is, if I upgrade an analyzer, the documentation won't be upgraded along with it. Ideally, we'd be able to include documentation files inside a plugin, and dynamically include that content in the embedded documentation.

      What

      We'll add the ability to dynamically pull documentation from plugins into the embedded docs. As part of this, we'll need to make sure the docs search index is always up to date and we'll need to allow plugins to update the navigation tree to insert their documents.

      Some documentation pages aggregate information from multiple plugins:

      This is separate from the main plugins' documentation. Example: https://docs.sonarqube.org/latest/analysis/languages/python/

      Plan:

      • The first step is to check if the documentation structure is good as it is or if there are plans to change it.
      • Then we will choose a way to retrieve the documentation from plugins. It could be an API, Markdown files, etc...
      • After that we can select a first plugin and embed the documentation in it. => sonar-dotnet#2481
      • We can modify SonarQube so that it retrieves the documentation, and validate with this first plugin.
      • Finally we add the documentation to the other plugins one by one.

      One important point is that some plugins will be released long after SonarQube is able to show their documentation.

      SonarQube has to:

      • display the embedded documentation when there's no doc provided by the plugin
      • merge the embedded documentation with whatever doc is available from plugins.

      This should apply to embedded plugins only.

      How

      Plugin side

      See MMF-1770 to follow which plugins have their documentation embedded and which don't.

      Plugins will ship with a single Markdown file inside the static/ folder. This file must be in the format static/documentation.md. The Markdown will be able to use the same formatting as the current documentation in sonar-docs. The only difference will concern the Header part (aka frontmatter), which will introduce a new required property: key. This is NOT the same as the plugin key. Instead, it should correspond to the "last part" of the documentation URL (e.g.: /analysis/languages/abap/, key = abap; /analysis/languages/cfamily/, key = cfamily). Furthermore, the url and nav properties will not apply to plugin documentation, and should be removed.

      Real-world example for HTML:

      ---
      title: HTML
      key: html
      ---
      
      <!-- static -->
      <!-- update_center:web -->
      <!-- /static -->
      
      
      ## Language-Specific Properties
      
      You can discover and update HTML-specific [properties](/analysis/analysis-parameters/) in:  <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > HTML](/#sonarqube-admin#/admin/settings?category=html)**.
      
      ## PHP Code Analysis
      SonarPHP and SonarHTML both analyze files with extensions: `.php`, `.php3`, `.php4`, `.php5`, `.phtml`.
      
      File metrics, such as the number of lines of code, can only be measured by one of the languages, PHP or HTML. They are handled by SonarPHP by default, and by SonarHTML if for some reason SonarPHP is not present.
      
      SonarHTML analyzes PHP files even if the PHP file extensions are not included in the list of file extensions to analyze.
      

      SonarQube side

      The Embedded documentation will fetch the list of all installed language analyzers (use a white-list?), and verify if any of them ship with a documentation file inside their static/ folder, by pinging the special /static/PLUGIN_NAME/FILE_NAME URL.

      If a documentation is found, it is fetched. After fetching, we do the following:

      • If a page with the same key already exists in sonar-docs, it is replaced (use the url for this)
      • If not, it is added to the page list

      This must happen before indexing, or, if it happens afterwards, we should find a way to refresh the index for only the updated page.

      Restrictions

      • This will only apply to languages (for now).
      • Third-party plugins cannot ship with their own documentation, and if they figure out how to do it, we should not display it (for now).
      • Only a single documentation page can be shipped with each plugin (for now).
      • The documentation page must have a pre-defined filename.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              christophe.levis Christophe Levis
              Reporter:
              ann.campbell.2 Ann Campbell
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: