Description

This app is supposed to be generic and usable by anyone wishing to use XWiki to document their software product, using Diataxis.

The idea is to create a contrib extension for the new Documentation strategy:

• Move the xclass/xsheet/xtemplate + generic pages from xwiki.org to this app
• Create a doc validation extension to validate a doc page on save vs the doc guide, to the maximum
• Automatically create doc pages on xwiki.org when importing a new extension (+ fill the extension id)
  • Related: https://jira.xwiki.org/browse/XWIKI-23574 (i.e. fill automatically the xproperty with the location of the doc)
• Display a badge listing the extension concerned by the doc and when clicking the badge, redirect to the extension page on exo
• and more...

Checker

• Create a Document Analyzer component role
  • Save the result in an xobject on the page itself. This could be considered as metadata related to the "last reviewed date" and "last reviewers" and put it all in the same XObject.
  • The analyzer does the analysos on the markup content (ie string-based analysis, using regexes or XDOM - both should be available to each analysis check)
• Add an Event Listener that triggers the analyzer if the doc has a Documentation XClass xobject, using the TaskManager (async)
• Add a docextra UIXP to add a "Documentation" tab
  • Have a button to force analysis
  • Display the status of the analysis in it (and grey out the analyze button when analysis is in progress)
  • Display the result of the analysis if available
• In the Documentation XSheet, if there are errors, display an error box with a link to the docextra Documentation tab

Format of Analysis result

Option 1

• Textarea field
• One entry per line
• Plain text

Example:

You cannot have more than...
There are image macros with...

Option 2

• One XObject per issue
• 1 string for the problem's description
• 1 textarea for the context of the problem (2 lines before and 2 lines after).

Checks

1. If the current doc appears in the doc navigation tree. Level = ERROR
2. If there are images not using the image macro. Level = ERROR
3. All image macros specify a "size". Level = WARNING/ERROR  (implemented in the image macro itself)
4. If multiple images next to each other, the Gallery macro must be used. Level = ERROR
5. If there are videos, the embed macro must be used. Disallow use of the video macro. Level = ERROR
6. The embed macro's "attachment" parameter must end in ".webm"
7. File extensions are lowercase. Level = ERROR  (implemented by the kebab-case check since it's supposed to be lowercase only)
8. Alt parameter used for image macros. Level = WARNING
9. kebab naming for pages. Level = ERROR
10. kebab naming for attachments. Level = ERROR
11. Verb for titles of howtos and tutorials. Level = ERROR
12. No verb for titles of explanation and references. Level = ERROR
13. The syntax is xwiki/2.1
14. Check for older version macros and warn to remove them = WARNING
15. If a page that is in the "/Doc" space doesn't have an object of type documentationClass or of type LandingPageClass -> ERROR Retracting this because there can be pages in the "/Doc" space that are meant to be used only within a display macro.

Outstanding Issues

• When saving with Change Request, the event listener won't be triggered and thus the doc writers using CR won't see violations and nor will the approvers... TODO: check with Simon what we can do.

Idea

• ? Enable on xwiki.org the Link Checker Application for missing links inside the "/Doc" space and add it in the violation list.