[Doc] Add troubleshooting guide about pkg_resources module not found error

[MortalHappiness]

Why are these changes needed?

See the description in the corresponding issue for details.

Related issue number

Resolves: #46205

Checks

• I've signed off every commit(by using the -s flag, i.e., git commit -s) in this PR.
• I've run scripts/format.sh to lint the changes in this PR.
• I've included any doc changes needed for https://docs.ray.io/en/master/.
  • I've added any new APIs to the API Reference. For example, if I added a
    method in Tune, I've added it in doc/source/tune/api/ under the
    corresponding .rst file.
• I've made sure the tests are passing. Note that there might be a few flaky tests, see the recent failures at https://flakey-tests.ray.io/
• Testing Strategy
  • Unit tests
  • Release tests
  • This PR is not tested :(

[MortalHappiness]

@kevin85421 Can you help me review this PR? Thanks.

[angelinalg]

Thank you for filing the issue and making this PR! @peytondmurray @can-anyscale, would you please review?

[peytondmurray]

@MortalHappiness What version of Python are you running?

I feel like I saw this with 3.12 and sphinxemoji==0.2.0, but I might be misremembering.

I'd prefer not to merge this as is, because the use of pkg_resources is deprecated in favor of importlib.resources. Instead I propose either:

1. Removing the sphinxemoji extension, which I really don't think we're using anywhere in our docs anyway, or
2. If we really have a want for this extension, just bump the version to 0.3.0, which should fix the issue

[can-anyscale]

i have seen this error with python 3.12 with other libraries as well; perhaps we can change the instruction to use python 3.11; i get a feeling that many packages out there doesn't work seamlessly with python 3.12 yet (or our requirements-doc.txt doesn't)

[can-anyscale]

but agree, setuptools is a dependency of almost everything in the python environment, it's good if our doc doesn't ask users to tamper with that package without understanding how that might impact other python libraries in users environment

[peytondmurray]

perhaps we can change the instruction to use python 3.11

I'd still vote to just bump the version or remove the extension. Active support for 3.11 has already ended months ago, so we should really be on 3.12 at the moment IMO, especially since the fix is so straightforward 🤷

[MortalHappiness]

My python version is 3.12. Actually the newest version of sphinxemoji has fixed this issue. So updating sphinxemoji to the latest version can fix this problem. However, there is another dependency with this problem:

ray/doc/requirements-doc.txt

Line 13 in 9e1d4fe

sphinxcontrib-redoc==1.6.0

See https://github.com/sphinx-contrib/redoc. It has not been updated for 4 years. Therefore setuptools still needs to be installed if we want to use that package.

[peytondmurray]

Maybe the right way to go then is to drop redoc and instead move to https://github.com/sphinx-contrib/openapi ? cc @angelinalg

[can-anyscale]

how much work will that be @peytondmurray?

[peytondmurray]

Probably not much - I'll build on a separate branch and send a screenshot to you and @angelinalg in a few minutes.

[can-anyscale]

put back to your queue since the doc team is thinking about solving this in a different way; thanks for bring this up issue

[peytondmurray]

Closing this, as it has been resolved by instead updating the doc build requirements in #46208.