Documentation and Examples

Contents

Documentation

  • Python and C documentation is built usingSphinx.

  • Each document is written inreStructuredText.

  • The documentation is thedoc/ directory.

  • You can build it locally usingmakehtml command.

    makehtml

    Runmakehelp to learn about the other commands.

The online document is hosted byRead the Docs where the imported project is managed byHyunsu Cho andJiaming Yuan.

Build the Python Docs using pip and Conda

  1. Create a conda environment.

    condacreate-nxgboost-docs--yespython=3.10

    Note

    Python 3.10 is required byxgboost_ray package.

  2. Activate the environment

    condaactivatexgboost-docs

  3. Install required packages (in the current environment) usingpip command.

    pipinstall-rrequirements.txt

    Note

    It is currently not possible to install the required packages usingcondadue toxgboost_ray being unavailable in conda channels.

    condainstall--filerequirements.txt--yes-cconda-forge

  4. (optional) Installgraphviz

    condainstallgraphviz--yes

  5. Eventually, build the docs.

    makehtml

You should see the following messages in the console:

$makehtmlsphinx-build -b html -d _build/doctrees   . _build/htmlRunning Sphinx v6.2.1...The HTML pages are in _build/html.Build finished. The HTML pages are in _build/html.

Read The Docs

Read the Docs (RTD for short) is an online document hostingservice and hosts theXGBoost document site. The document builder used by RTD isrelatively lightweight. However some of the packages like the R binding require a compiledXGBoost along with all the optional dependencies to render the document. As a result, bothjvm-based packages and the R package’s document is built with an independent CI pipelineand fetched during online document build.

The sphinx configuration filexgboost/doc/conf.py acts as the fetcher. During build,the fetched artifacts are stored inxgboost/doc/tmp/jvm_docs andxgboost/doc/tmp/r_docs respectively. For the R package, there’s a dummy index file inxgboost/doc/R-package/r_docs . Jvm doc is similar. As for the C doc, it’s generatedusing doxygen and processed by breathe during build as it’s relatively cheap. Thegenerated xml files are stored inxgboost/doc/tmp/dev .

Thexgboost/doc/tmp is part of thehtml_extra_path sphinx configuration specifiedin theconf.py file, which informs sphinx to copy the extracted html files to thebuild directory. Following is a list of environment variables used by the fetchers inconf.py:

  • READTHEDOCS: Read the docs flag. Build the full documentation site including R, JVM andC doc when set toTrue (case sensitive).

  • XGBOOST_R_DOCS: Local path for pre-built R document, used for development. If itpoints to a file that doesn’t exist, the configuration script will download thepackaged document to that path for future reuse.

  • XGBOOST_JVM_DOCS: Local path for pre-built JVM document, used fordevelopment. Similar to the R docs environment variable when it points to a non-existentfile.

As of writing, RTD doesn’t provide any facility to be embedded as a GitHub action but weneed a way to specify the dependency between the CI pipelines and the document build inorder to fetch the correct artifact. The workaround is to use an extra GA step to notifyRTD using itsREST API.

Examples

  • Use cases and examples are indemo directory.

  • We are super excited to hear about your story. If you have blog posts,tutorials, or code solutions using XGBoost, please tell us, and we will adda link in the example pages.