[TASK] Prepare documentation of multiple CVA6 variants

[cathales]

Task Description

#1691 plans to document several variants of the CVA6. This is a big piece of work. To make this work easier, some preparation is needed first:

• no warning shall be emitted. It makes new warnings easier to notice (and to fix!)
• everything shall be done to help keeping doc DRY and not duplicating information between CVA6 variants.

Required Changes

About CSR documentation files:

• [ ] Fix warnings (section underlines, ``( and other formating issues).
• [ ] Remove part-name prefixes from filenames. This part number is already in the path.
• [ ] Reformat the files to get a better display after Sphinx rendenring (there are currently too many section titles).
• [ ] Resize tables to fit in page size.

About templating:

• [ ] Setup templating in the documentation.

The goal is to have in the sphinx documentation several variants (CV32A60X, CV32A60AX,…), which are derived from a master documentation.

Misc:

• [ ] Do not use md anymore. Replace used md files by rst files (pandoc can help). The currently used Sphinx extension for Markdown is deprecated: remove this extension.
• [ ] Setup sphinx.ext.autosectionlabel with autosectionlabel_prefix_document option. Check that it fixes the label double-declaration warnings, especially in documents .. include::d several times. Requires the update of all :ref:s.
• [ ] Disable the "bibliography item must be used" check.
• [ ] Add a GitHub action to check that the documentation is correctly generated before merging PRs. Bonus point if it is possible to browse the built documentation.

Current Status

There are many warnings to fix and we do not have set up templating.

Risks

No templating solution was chosen yet. Options may involve additional steps in the flow, which would be a huge drawback and will be important to take decision.

Yet identified (partial) solutions include:

• Having a Jinja flow run before building Sphinx documentation
• sphinx-jinja -- "A sphinx extension to include jinja based templates based documentation into a sphinx doc"
• Having our custom extension to fit our needs.
• Parsing SV configuration files to get attributes: "does XXX configuration enable YYY option?"

Prerequisites

No response

KPI (KEY Performance Indicators)

No response

Description of Done

See task list in Required Changes

Associated PRs

No response

[cathales]

@JeanRochCoulon Can you please review this task description and add it to the Kanban board?

Also, please add it as a prerequisite of #1691. It may be good to remove duplicated contents from #1691 too.