[docs] How to build the docs on macOS using conda

[jaceklaskowski]

1. Describe the steps to build the docs on macOS using conda in "Contribute to XGBoost"
2. Fix a typo in "XGBoost JVM Package" main page

[trivialfis]

Thank you for the detailed instructions on building the documents, @jaceklaskowski ! Some comments on the details.

[trivialfis]

Since you use conda for illustration, it should work across various platforms. We just need to replace the brew step with graphviz from conda forge.

Aside from this, let's make it clear that this is building the HTML document.

[trivialfis]

I installed the required packages from conda with packages from the conda-forge channel.

Would be great to keep the toolchain as consistent as possible.

[jaceklaskowski]

The issue I had was with ray and Python version. I started with Python 3.11 and make html couldn't resolve xgboost-ray. Once I switched to Python 3.10 it all started well but only with pip. I couldn't convince conda to resolve all the deps. I'll give it a try again and report back with the findings.

[jaceklaskowski]

This is the issue I'm facing with conda install. Any idea how to fix it (and how it's possible that it works for you?!)

$ conda install --file requirements.txt --yes -c conda-forge
Collecting package metadata (current_repodata.json): done
Solving environment: unsuccessful initial attempt using frozen solve. Retrying with flexible solve.
Collecting package metadata (repodata.json): done
Solving environment: unsuccessful initial attempt using frozen solve. Retrying with flexible solve.

PackagesNotFoundError: The following packages are not available from current channels:

  - xgboost_ray

Current channels:

  - https://conda.anaconda.org/conda-forge/osx-64
  - https://conda.anaconda.org/conda-forge/noarch
  - https://repo.anaconda.com/pkgs/main/osx-64
  - https://repo.anaconda.com/pkgs/main/noarch
  - https://repo.anaconda.com/pkgs/r/osx-64
  - https://repo.anaconda.com/pkgs/r/noarch

To search for alternate channels that may provide the conda package you're
looking for, navigate to

    https://anaconda.org

and use the search bar at the top of the page.

[trivialfis]

This doesn't build the C++ doc, which requires the C++ document tools like doxygen. After having doxygen, one can run:

READTHEDOCS=True make html

[jaceklaskowski]

The C++-part of xgboost was of little to no interest to me honestly and so I didn't even bother myself with this. I also simply followed the current version of the doc how to use make html and since there was no mention about the other options I didn't add them either.

[trivialfis]

A reference to the sphinx doc build would be great. There are many other options like output format, each with a different set of dependencies (like pdflatex for pdf).

[jaceklaskowski]

A reference to the sphinx doc build would be great. is already included in the Documentation section at the top of the page so I skip this. I added a note about the other options (make help).

[trivialfis]

Thank you for improving the doc, @jaceklaskowski !

[trivialfis]

Some edits:

• Remove the macOS-specific header since conda is cross-platform.
• Specify this is only for Python.