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.

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

Standardize doc building workflows #75

Open
vyasr opened this issue Jun 28, 2024 · 0 comments
Open

Standardize doc building workflows #75

vyasr opened this issue Jun 28, 2024 · 0 comments

Comments

@vyasr
Copy link
Contributor

vyasr commented Jun 28, 2024

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 rapidsai/cudf#13789 (comment).

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant