Cleanup gh-pages after recent nav changes

[jasonmadigan]

https://github.com/Kuadrant/authorino/pull/513/files#r1920158568

We still have a bunch of old docs published that will resolve on dev, despite them no longer being in the nav for main / dev. For example:

https://docs.kuadrant.io/dev/authorino-operator/#installing-via-olm

^ no longer in the nav, so is an orphan doc. We probably need to go through gh-pages and clean these up manually, otherwise they'll go stale

[david-martin]

Pages exist that link to some of these docs that are still published (despite not being in the nav anymore).
To verify this, I removed a number of imports for the authorino component and tried start mkdocs locally, just leaving the remaining page referenced from the nav:

        - name: authorino
          import_url: 'https://github.com/kuadrant/authorino?edit_uri=/blob/main/&branch=main'
          imports:
            - /docs/user-guides/observability.md

I got this error on main:

WARNING -  Doc file 'authorino/docs/user-guides/observability.md' contains a link '../architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time', but the target 'authorino/docs/architecture.md' is not found among documentation files.
WARNING -  Doc file 'authorino/docs/user-guides/observability.md' contains a link '../architecture.md#raw-http-authorization-interface', but the target 'authorino/docs/architecture.md' is not found among documentation files.

I suspect there may be other dangling files like this if you clean up other imports for other repos.

The root of the problem here is that there's an expectation (a reasonable one) that all pages served on the docs site should also be in the nav somewhere.
Otherwise, that page can't be navigated to easily, and instead relies on some link hidden on some other page somewhere.

Unfortunately, the mkdocs multirepo nav_repo config imports all files that match the import file list/globs, regardless of if they are used or not.

One option to find all dangling pages and put some guardrails in place for future is to explicitly list every file in the nav_repos block to be imported, and avoid using globs. This would be a one time tedious task, but shouldn't take long.

[jasonmadigan]

One option to find all dangling pages and put some guardrails in place for future is to explicitly list every file in the nav_repos block to be imported, and avoid using globs. This would be a one time tedious task, but shouldn't take long.

I can take a look at this, see if we can't add some automation to detect such dangling. Wouldn't necessarily make it a PR blocker, but it would be good if we could detect, so we can hone imports (ideally, moving away from globs - the nav is explicit, we'd ideally mirror that for file imports)

[jasonmadigan]

@david-martin working on a draft: #188