We use Sphinx to build our Python docs (and in the case of raft and cudf, also the C++ docs using breathe). Sphinx docs mention that builds may be done by directly invoking sphinx-build, but the sphinx-quickstart program that projects use to initialize a Sphinx doc tree creates a Makefile, and using make mentioned immediately afterwards in the official Sphinx docs. Almost all projects using Sphinx in the wild use make html rather than invoking sphinx-build directly. This is also typically reflected in their contributing guides for new developers. Using the Makefile is especially valuable because it centralizes the sphinx-build options to use so that building in different environments produces the same result. These issues are discussed in greater depth at https://github.com/rapidsai/cudf/pull/13789#discussion_r1280731418.
Currently RAPIDS libraries are not so consistent about this. We mostly use sphinx-build directly in our ci/build_docs.sh scripts because that was chosen during the Jenkins->GH actions transition. Meanwhile, a few build.sh scripts support building docs, some with make and others with sphinx-build.
We should standardize all of our build scripts across different repositories to consistently use make.
We use Sphinx to build our Python docs (and in the case of raft and cudf, also the C++ docs using breathe). Sphinx docs mention that builds may be done by directly invoking
sphinx-build, but thesphinx-quickstartprogram that projects use to initialize a Sphinx doc tree creates a Makefile, and using make mentioned immediately afterwards in the official Sphinx docs. Almost all projects using Sphinx in the wild usemake htmlrather than invokingsphinx-builddirectly. This is also typically reflected in their contributing guides for new developers. Using the Makefile is especially valuable because it centralizes the sphinx-build options to use so that building in different environments produces the same result. These issues are discussed in greater depth at https://github.com/rapidsai/cudf/pull/13789#discussion_r1280731418.Currently RAPIDS libraries are not so consistent about this. We mostly use
sphinx-builddirectly in our ci/build_docs.sh scripts because that was chosen during the Jenkins->GH actions transition. Meanwhile, a few build.sh scripts support building docs, some withmakeand others withsphinx-build.We should standardize all of our build scripts across different repositories to consistently use
make.