IBX-9609: Upgrade mkdocs

[adriendupuis]

Question	Answer
JIRA Ticket	IBX-9609
Versions	All
Edition	All

Upgrade mkdocs, python&pip, and all requirements.txt entries to their latest version.

• MkDocs 1.5.1 → 1.6.1
  • Test internal anchor link, report them as INFO during build or at server start up.
    • INFO - Doc file 'templating/layout/add_navigation_menu.md' contains a link '../twig_function_reference/url_twig_functions.md#ibexa.url.alias', but the doc 'templating/twig_function_reference/url_twig_functions.md' does not contain an anchor '#ibexa.url.alias'. fixed in Fix links #2625
  • Remove NBSP when building the ToC
  • Prevent Fix not rendered code sample #2637 to happen
  • Different behavior with navigation duplicates (Remove "Update from v2.5 > Update to latest v3.3" from nav #2632)
  • Allow absolute links relative to docs/ dir
• Material for MkDocs 9.1.1 → 9.6.5
  • Update CSS to compensate theme changes
• Pygments 2.15.0 → 2.19.1
  • Add JSX colorization (2.17.0)
    • Before
    • After

Also applied in ibexa/documentation-user#334

MkDocs Validation Feature

We previously used the default validation settings and I suggest we continue with defaults.

The strict mode is used when building the online doc which means that warn and error levels are blocking the deployment.

validation:
  nav:
    omitted_files: info # The whole `snippets/` directory and `search_results.md` are genuinely absent from navigation.
    not_found: warn # If a file from the ToC is not found, deployment is stopped.
    absolute_links: info # In the ToC, a link starting with a slash is seen as external. `INFO    -  An absolute path to '/…' is included in the 'nav' configuration, which presumably points to an external resource.` I didn't manage the exact behavior as python crashes afterward. It could be increased to `error`
  links:
    not_found: warn # A broken link was already stopping deployment. It's important and can stay this way. `WARNING -  AutoLinksPlugin unable to find … in directory …` `WARNING -  Doc file '…' contains a link '…', but the target '…' is not found among documentation files.` 
    anchors: info # If an internal link target an unknown anchor, it will be only reported in build log. No need to stop deployment, the page is there. But we have to discipline ourself and look at the log as it can be confusing to land on a tall page and to have to find out why here and what should be read.
    absolute_links:  info # By default, a link starting with a slash is seen as external. It can be changed to the special value `relative_to_docs` so it would be recognized as below the `docs/` dir. As `mkdocs-autolinks-plugin` is used, it useless for Markdow files, but this could be very useful for PHP API reference and its HTML files!
    unrecognized_links: info # TODO

Checklist

• Text renders correctly
• Text has been checked with vale
• Description metadata is up to date
• Redirects cover removed/moved pages
• Code samples are working
• PHP code samples have been fixed with PHP CS fixer
• Added link to this PR in relevant JIRA ticket or code PR

[github-actions]

Preview of modified Markdown: no Markdown change to preview.

[adriendupuis]

Test script

for branch in 'master' '4.6' '3.3'; do
  git checkout $branch
  git checkout HEAD -- requirements.txt
  pip install -r requirements.txt
  mkdocs build --clean --site-dir "./html.$branch" --config-file mkdocs.yml --strict
  git checkout IBX-9609-upgrade-requirements -- requirements.txt
  pip install -r requirements.txt
  mkdocs build --clean --site-dir "./html.$branch.upgraded" --config-file mkdocs.yml --strict
  diff -rbBw --exclude=assets ./html.$branch ./html.$branch.upgraded > diff.$branch.txt
  cat diff.$branch.txt \
    | grep -v 'meta name="generator"' \
    | grep -v '<meta name="robots" content="noindex">' \
    | grep -v -i 'redirect' \
    | grep -v '<changefreq>daily</changefreq>' \
    | grep -v '\.min\.css' \
    | grep -v '\.min\.js' \
    | grep -v 'id="__config"' \
    | grep -v '__md_scope' \
    | grep -v 'generateStopWordFilter' \
    | grep -v '__md_get("__tabs")' \
    | grep -v '__tabbed_' \
    | grep -v 'path d="M' \
    | grep -v 'nav class="md-header__inner' \
    | grep -v 'md-nav--secondary' \
    | grep -v 'data-md-component="top"' \
    | grep -v 'class="source-github"' \
    | grep -v 'align="left"' | grep -v 'style="text-align: left;"' \
    | grep -v 'align="center"' | grep -v 'style="text-align: center;"' \
    | grep -v '^> *$' \
    > diff.$branch.filtered.txt
done

grep -v come for a first review of diff.$branch.txt.
No big changes found, like JSX colorization, NBSP removal, linefeeds difference between tags when rendering <detail>,…