diff --git a/doc/contrib/docs.rst b/doc/contrib/docs.rst index c4249dbb7..df2b2692a 100644 --- a/doc/contrib/docs.rst +++ b/doc/contrib/docs.rst @@ -8,23 +8,83 @@ Documentation and Examples :backlinks: none :local: -********* -Documents -********* +************* +Documentation +************* * Python and C documentation is built using `Sphinx `_. * Each document is written in `reStructuredText `_. -* You can build document locally to see the effect, by running +* The documentation is the ``doc/`` directory. +* You can build it locally using ``make html`` command. -.. code-block:: bash + .. code-block:: bash - make html + make html -inside the ``doc/`` directory. The online document is hosted by `Read the Docs `__ where the imported project is managed by `Hyunsu Cho `__ and `Jiaming Yuan `__. + Run ``make help`` to learn about the other commands. + +The online document is hosted by `Read the Docs `__ where the imported project is managed by `Hyunsu Cho `__ and `Jiaming Yuan `__. + +========================================= +Build the Python Docs using pip and Conda +========================================= + +#. Create a conda environment. + + .. code-block:: bash + + conda create -n xgboost-docs --yes python=3.10 + + .. note:: Python 3.10 is required by `xgboost_ray `__ package. + +#. Activate the environment + + .. code-block:: bash + + conda activate xgboost-docs + +#. Install required packages (in the current environment) using ``pip`` command. + + .. code-block:: bash + + pip install -r requirements.txt + + .. note:: + It is currently not possible to install the required packages using ``conda`` + due to ``xgboost_ray`` being unavailable in conda channels. + + .. code-block:: bash + + conda install --file requirements.txt --yes -c conda-forge + + +#. (optional) Install `graphviz `__ + + .. code-block:: bash + + conda install graphviz --yes + +#. Eventually, build the docs. + + .. code-block:: bash + + make html + + You should see the following messages in the console: + + .. code-block:: console + + $ make html + sphinx-build -b html -d _build/doctrees . _build/html + Running Sphinx v6.2.1 + ... + The HTML pages are in _build/html. + + Build finished. The HTML pages are in _build/html. ******** Examples ******** -* Use cases and examples will be in `demo `_. +* Use cases and examples are in `demo `_ 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 add a link in the example pages. diff --git a/doc/jvm/index.rst b/doc/jvm/index.rst index 2b476781b..a92834d74 100644 --- a/doc/jvm/index.rst +++ b/doc/jvm/index.rst @@ -23,8 +23,8 @@ Installation :local: :backlinks: none -Checkout the :doc:`Installation Guide ` for how to install jvm package, or -:doc:`Building from Source ` on how to build it form source. +Checkout the :doc:`Installation Guide ` for how to install the jvm package, or +:doc:`Building from Source ` on how to build it from the sources. ******** Contents