diff --git a/doc/conf.py b/doc/conf.py index 8e8eb2328..0a90fa297 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -21,8 +21,6 @@ import urllib.request 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,49 @@ def run_doxygen(): os.chdir(curdir) +def build_jvm_docs(): + """Build docs for the JVM packages""" + git_branch = os.getenv("READTHEDOCS_VERSION_NAME", default=None) + print(f"READTHEDOCS_VERSION_NAME = {git_branch}") + + 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): + """ + 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 +116,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 +162,7 @@ sphinx_gallery_conf = { "../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 000000000..b9e7821aa --- /dev/null +++ b/doc/jvm/api.rst @@ -0,0 +1,8 @@ +############################# +API Docs for the JVM packages +############################# + +* `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>`_ diff --git a/doc/jvm/index.rst b/doc/jvm/index.rst index a92834d74..0a2e947ea 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::