Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 3 commits into from
Jun 14, 2023
Merged

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

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0e0946f
[docs] Changes to the docs
jaceklaskowski Jun 8, 2023
4418009
Addressing review comments
jaceklaskowski Jun 9, 2023
b32e7ba
Remove the reference to macos, note about Python.
trivialfis Jun 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 68 additions & 8 deletions doc/contrib/docs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,23 +8,83 @@ Documentation and Examples
:backlinks: none
:local:

*********
Documents
*********
*************
Documentation
*************
* Python and C documentation is built using `Sphinx <http://www.sphinx-doc.org/en/master/>`_.
* Each document is written in `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
* 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 <https://readthedocs.org/>`__ where the imported project is managed by `Hyunsu Cho <https://github.com/hcho3>`__ and `Jiaming Yuan <https://github.com/trivialfis>`__.
Run ``make help`` to learn about the other commands.

The online document is hosted by `Read the Docs <https://readthedocs.org/>`__ where the imported project is managed by `Hyunsu Cho <https://github.com/hcho3>`__ and `Jiaming Yuan <https://github.com/trivialfis>`__.

===============================
Build Docs on macOS using Conda
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

===============================
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


#. 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 <https://github.com/ray-project/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 <https://www.graphviz.org/>`__

.. 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).


********
Examples
********
* Use cases and examples will be in `demo <https://github.com/dmlc/xgboost/tree/master/demo>`_.
* Use cases and examples are in `demo <https://github.com/dmlc/xgboost/tree/master/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.
4 changes: 2 additions & 2 deletions doc/jvm/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@ Installation
:local:
:backlinks: none

Checkout the :doc:`Installation Guide </install>` for how to install jvm package, or
:doc:`Building from Source </build>` on how to build it form source.
Checkout the :doc:`Installation Guide </install>` for how to install the jvm package, or
:doc:`Building from Source </build>` on how to build it from the sources.

********
Contents
Expand Down