From e6fd3f1d812e5f7840c7a60ba0c5c0a6374bb5f5 Mon Sep 17 00:00:00 2001 From: Hyunsu Cho Date: Mon, 3 Jun 2024 23:27:10 -0700 Subject: [PATCH 1/4] [Doc] Fix deployment for JVM docs --- doc/conf.py | 72 ++++++++++++++++++++++++----------------------- doc/jvm/api.rst | 8 ++++++ doc/jvm/index.rst | 5 +--- 3 files changed, 46 insertions(+), 39 deletions(-) create mode 100644 doc/jvm/api.rst diff --git a/doc/conf.py b/doc/conf.py index 8e8eb2328302..3e68f3de68cf 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -21,8 +21,6 @@ import warnings from urllib.error import HTTPError -from sh.contrib import git - CURR_PATH = os.path.dirname(os.path.abspath(os.path.expanduser(__file__))) PROJECT_ROOT = os.path.normpath(os.path.join(CURR_PATH, os.path.pardir)) TMP_DIR = os.path.join(CURR_PATH, "tmp") @@ -61,6 +59,41 @@ def run_doxygen(): os.chdir(curdir) +def build_jvm_docs(): + """Build docs for the JVM packages""" + git_branch = os.getenv("READTHEDOCS_GIT_IDENTIFIER", default=None) + print(f"git_branch = {git_branch}") + + def try_fetch_jvm_doc(branch): + """ + Attempt to fetch JVM docs for a given branch. + Returns True if successful + """ + try: + url = f"https://s3-us-west-2.amazonaws.com/xgboost-docs/{branch}.tar.bz2" + filename, _ = urllib.request.urlretrieve(url) + if not os.path.exists(TMP_DIR): + print(f"Create directory {TMP_DIR}") + os.mkdir(TMP_DIR) + jvm_doc_dir = os.path.join(TMP_DIR, "jvm_docs") + if os.path.exists(jvm_doc_dir): + print(f"Delete directory {jvm_doc_dir}") + shutil.rmtree(jvm_doc_dir) + print(f"Create directory {jvm_doc_dir}") + os.mkdir(jvm_doc_dir) + + with tarfile.open(filename, "r:bz2") as t: + t.extractall(jvm_doc_dir) + return True + except HTTPError: + print(f"JVM doc not found at {url}. Skipping...") + return False + + if not try_fetch_jvm_doc(git_branch): + print(f"Falling back to the master branch...") + try_fetch_jvm_doc("master") + + def is_readthedocs_build(): if os.environ.get("READTHEDOCS", None) == "True": return True @@ -75,40 +108,9 @@ def is_readthedocs_build(): if is_readthedocs_build(): run_doxygen() + build_jvm_docs() -git_branch = os.getenv("SPHINX_GIT_BRANCH", default=None) -if not git_branch: - # If SPHINX_GIT_BRANCH environment variable is not given, run git - # to determine branch name - git_branch = [ - re.sub(r"origin/", "", x.lstrip(" ")) - for x in str(git.branch("-r", "--contains", "HEAD")).rstrip("\n").split("\n") - ] - git_branch = [x for x in git_branch if "HEAD" not in x] -else: - git_branch = [git_branch] -print("git_branch = {}".format(git_branch[0])) - -try: - filename, _ = urllib.request.urlretrieve( - f"https://s3-us-west-2.amazonaws.com/xgboost-docs/{git_branch[0]}.tar.bz2" - ) - if not os.path.exists(TMP_DIR): - print(f"Create directory {TMP_DIR}") - os.mkdir(TMP_DIR) - jvm_doc_dir = os.path.join(TMP_DIR, "jvm") - if os.path.exists(jvm_doc_dir): - print(f"Delete directory {jvm_doc_dir}") - shutil.rmtree(jvm_doc_dir) - print(f"Create directory {jvm_doc_dir}") - os.mkdir(jvm_doc_dir) - - with tarfile.open(filename, "r:bz2") as t: - t.extractall(jvm_doc_dir) -except HTTPError: - print("JVM doc not found. Skipping...") - # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -152,7 +154,7 @@ def is_readthedocs_build(): "../demo/dask", "../demo/aft_survival", "../demo/gpu_acceleration", - "../demo/rmm_plugin" + "../demo/rmm_plugin", ], # path to where to save gallery generated output "gallery_dirs": [ diff --git a/doc/jvm/api.rst b/doc/jvm/api.rst new file mode 100644 index 000000000000..67fb9ccaca7d --- /dev/null +++ b/doc/jvm/api.rst @@ -0,0 +1,8 @@ +############################# +API Docs for the JVM packages +############################# + +* `XGBoost4J Java API <../jvm_docs/javadocs/index>`_ +* `XGBoost4J Scala API <../jvm_docs/scaladocs/xgboost4j/index>`_ +* `XGBoost4J-Spark Scala API <../jvm_docs/scaladocs/xgboost4j-spark/index>`_ +* `XGBoost4J-Flink Scala API <../jvm_docs/scaladocs/xgboost4j-flink/index>`_ diff --git a/doc/jvm/index.rst b/doc/jvm/index.rst index a92834d747e0..0a2e947ea586 100644 --- a/doc/jvm/index.rst +++ b/doc/jvm/index.rst @@ -37,10 +37,7 @@ Contents XGBoost4J-Spark Tutorial XGBoost4J-Spark-GPU Tutorial Code Examples - XGBoost4J Java API - XGBoost4J Scala API - XGBoost4J-Spark Scala API - XGBoost4J-Flink Scala API + API docs .. note:: From 462cb2ce54c12bbf5fdc02a8f27939e6e3680337 Mon Sep 17 00:00:00 2001 From: Hyunsu Cho Date: Mon, 3 Jun 2024 23:41:57 -0700 Subject: [PATCH 2/4] Use READTHEDOCS_VERSION_NAME --- doc/conf.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 3e68f3de68cf..22c156e5cbae 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -61,9 +61,14 @@ def run_doxygen(): def build_jvm_docs(): """Build docs for the JVM packages""" - git_branch = os.getenv("READTHEDOCS_GIT_IDENTIFIER", default=None) + git_branch = os.getenv("READTHEDOCS_VERSION_NAME", default=None) print(f"git_branch = {git_branch}") + if git_branch == "latest": + git_branch = "master" + elif git_branch == "stable": + git_branch = f"release_{version}" + def try_fetch_jvm_doc(branch): """ Attempt to fetch JVM docs for a given branch. From 0d5ae8e5e41824a5c90adc7f0a01488a0e0eae3d Mon Sep 17 00:00:00 2001 From: Hyunsu Cho Date: Tue, 4 Jun 2024 00:37:07 -0700 Subject: [PATCH 3/4] Fix html --- doc/jvm/api.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/jvm/api.rst b/doc/jvm/api.rst index 67fb9ccaca7d..b9e7821aa6fa 100644 --- a/doc/jvm/api.rst +++ b/doc/jvm/api.rst @@ -2,7 +2,7 @@ API Docs for the JVM packages ############################# -* `XGBoost4J Java API <../jvm_docs/javadocs/index>`_ -* `XGBoost4J Scala API <../jvm_docs/scaladocs/xgboost4j/index>`_ -* `XGBoost4J-Spark Scala API <../jvm_docs/scaladocs/xgboost4j-spark/index>`_ -* `XGBoost4J-Flink Scala API <../jvm_docs/scaladocs/xgboost4j-flink/index>`_ +* `XGBoost4J Java API <../jvm_docs/javadocs/index.html>`_ +* `XGBoost4J Scala API <../jvm_docs/scaladocs/xgboost4j/index.html>`_ +* `XGBoost4J-Spark Scala API <../jvm_docs/scaladocs/xgboost4j-spark/index.html>`_ +* `XGBoost4J-Flink Scala API <../jvm_docs/scaladocs/xgboost4j-flink/index.html>`_ From 9c7534b21dd89bb65d7fa7bb03e07c1f2a5065df Mon Sep 17 00:00:00 2001 From: Hyunsu Cho Date: Tue, 4 Jun 2024 11:21:45 -0700 Subject: [PATCH 4/4] Default to master --- doc/conf.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 22c156e5cbae..0a90fa297bef 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -62,12 +62,15 @@ def run_doxygen(): def build_jvm_docs(): """Build docs for the JVM packages""" git_branch = os.getenv("READTHEDOCS_VERSION_NAME", default=None) - print(f"git_branch = {git_branch}") + print(f"READTHEDOCS_VERSION_NAME = {git_branch}") - if git_branch == "latest": + if not git_branch: + git_branch = "master" + elif git_branch == "latest": git_branch = "master" elif git_branch == "stable": git_branch = f"release_{version}" + print(f"git_branch = {git_branch}") def try_fetch_jvm_doc(branch): """