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.
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/
- 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.
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:
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.
- 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.