Update documentation requirements

[samjwu]

Update documentation to use version 0.11.0 of rocm-docs-core.

[cgmb]

Do you know why the build on readthedocs.org failed? It looks like it tried to query the branch and failed somehow.

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/hipsolver/envs/161/lib/python3.8/site-packages/sphinx/events.py", line 94, in emit
    results.append(listener.handler(self.app, *args))
  File "/home/docs/checkouts/readthedocs.org/user_builds/hipsolver/envs/161/lib/python3.8/site-packages/rocm_docs/projects.py", line 282, in _update_config
    default = _load_mapping(
  File "/home/docs/checkouts/readthedocs.org/user_builds/hipsolver/envs/161/lib/python3.8/site-packages/rocm_docs/projects.py", line 234, in _load_mapping
    _, branch = util.get_branch(repo_path)
  File "/home/docs/checkouts/readthedocs.org/user_builds/hipsolver/envs/161/lib/python3.8/site-packages/rocm_docs/util.py", line 61, in get_branch
    assert match is not None
AssertionError

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/hipsolver/envs/161/lib/python3.8/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/home/docs/checkouts/readthedocs.org/user_builds/hipsolver/envs/161/lib/python3.8/site-packages/sphinx/application.py", line 247, in __init__
    self.events.emit('config-inited', self.config)
  File "/home/docs/checkouts/readthedocs.org/user_builds/hipsolver/envs/161/lib/python3.8/site-packages/sphinx/events.py", line 105, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function _update_config at 0x7fea3317d8b0> for event 'config-inited' threw an exception (exception: )

Extension error (rocm_docs.projects):
Handler <function _update_config at 0x7fea3317d8b0> for event 'config-inited' threw an exception (exception: )
some
some
some
some

On a semi-related note: the docs should be buildable from a tarball when building locally (not just from a git repo), so please be careful when querying for branches. They legitimately might not exist.

[samjwu]

For the .org build, we want to phase out the Community version in favor of the additional features (ad control, auth, private builds, etc.).

You're right about the branch querying. We have an issue out to document usage of the new mapping feature (along with an eventual user guide), but it's just taken a backseat to high priority items.

[saadrahim]

@cgmb thanks for the observation on zip/tarball builds. I believe we query git information for parts of documentation. A fallback if no git information exists is needed. I created a new issue for this at ROCm/rocm-docs-core#194

[cgmb]

I don't see a good reason for this to fail on readthedocs.org. It's failing on this assert. It would be simpler and more robust to parse the URL with urllib.parse anyway. Trying to parse the URL with a regex is just asking for trouble.

[samjwu]

I don't see a good reason for this to fail on readthedocs.org. It's failing on this assert. It would be simpler and more robust to parse the URL with urllib.parse anyway. Trying to parse the URL with a regex is just asking for trouble.

Unfortunately it looks like urlparse cannot handle SSH remotes correctly, which are sometimes set in the READTHEDOCS_GIT_CLONE_URL environment variable (eg: [email protected]:RadeonOpenCompute/rocm-docs-core.git is simply parsed as the path variable, so we would still need the same regex to extract the organization and repository name)

[cgmb]

I've updated the hipsolver readthedocs configuration so this will pass, and will open a PR on rocm-docs-core to improve the error messages for next time.