Sphinx setup for sdk docs generation

Signed-off-by: shivas1516 <[email protected]>

.gitignore

@@ -78,3 +78,4 @@ $RECYCLE.BIN/
 
 ## Vendor dir
 vendor
+venv

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/sdkdocs/source/conf.py
+
+python:
+  install:
+    - requirements: docs/sdkdocs/requirements.txt
+
+formats:
+  - pdf
+  - epub

docs/sdkdocs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/sdkdocs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/sdkdocs/requirements.txt

@@ -0,0 +1,18 @@
+autodocsumm==0.2.13
+grpcio
+grpcio-tools
+kubeflow-katib
+kubernetes==30.1.0
+m2r2==0.3.3.post2
+Sphinx==7.4.7
+sphinx-click==6.0.0
+sphinx-rtd-theme==2.0.0
+sphinx-toggleprompt==0.5.2
+sphinx_immaterial==0.12.2
+sphinxcontrib-applehelp==2.0.0
+sphinxcontrib-devhelp==2.0.0
+sphinxcontrib-htmlhelp==2.1.0
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==2.0.0
+sphinxcontrib-serializinghtml==2.0.0

docs/sdkdocs/source/_static/custom.css

@@ -0,0 +1 @@
+[data-md-color-primary=katibblue]{--md-primary-fg-color:#4279f4;--md-primary-fg-color--light:##4279f4;--md-primary-fg-color--dark:##4279f4;--md-primary-bg-color:#fff;--md-primary-bg-color--light:hsla(0,0%,100%,.7)}

docs/sdkdocs/source/conf.py

@@ -0,0 +1,157 @@
+# Configuration file for the Sphinx documentation builder.
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../../sdk/python/v1beta1/kubeflow/katib'))
+
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Katib SDK APIs Reference'
+copyright = '2024, Kubflow Author'
+author = 'Kubflow Author'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = ''
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# Extensions
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
+    'sphinx_click',
+    'm2r2',
+    'sphinx_immaterial',
+    'autodocsumm',
+    'sphinx_toggleprompt',
+]
+
+# Autodoc settings
+autodoc_member_order = 'bysource'
+autodoc_default_options = {
+    'members': True,
+    'imported-members': True,
+    'undoc-members': True,
+    'show-inheritance': False,
+    'autosummary': True,
+}
+
+
+# Paths
+templates_path = ['_templates']
+html_static_path = ['_static']
+html_logo = '_static/kubeflow.png'
+html_favicon = '_static/favicon.ico'
+
+# The master toctree document.
+master_doc = 'index'
+
+# You can specify multiple suffix as a list of string:
+source_suffix = ['.rst', '.md']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+htmlhelp_basename = 'Kubeflowkatibsdoc'
+
+# Theme settings
+html_theme = 'sphinx_immaterial'
+html_theme_options = {
+    # Repository information
+    'repo_url': 'https://github.com/kubeflow/katib',
+    'repo_name': 'katib',
+    'edit_uri': 'blob/master/docs',
+
+    # Navigation and layout features
+    'features': [
+        'navigation.expand',
+        'navigation.sections',
+        'navigation.top',
+        'search.highlight',
+        'search.share',
+        'toc.follow',
+        'toc.sticky',
+    ],
+
+    # Color schemes
+    'palette': [
+        {
+            'media': '(prefers-color-scheme: light)',
+            'scheme': 'default',
+            'primary': 'katibblue',
+            'accent': 'light-blue',
+            'toggle': {
+                'icon': 'material/weather-night',
+                'name': 'Switch to dark mode',
+            }
+        },
+        {
+            'media': '(prefers-color-scheme: dark)',
+            'scheme': 'slate',
+            'primary': 'katibblue',
+            'accent': 'light-blue',
+            'toggle': {
+                'icon': 'material/weather-sunny',
+                'name': 'Switch to light mode',
+            }
+        }
+    ],
+
+    # Font settings
+    'font': {
+        'text': 'Open Sans',
+        'code': 'Roboto Mono',
+    },
+
+    # Icon settings
+    'icon': {
+        'repo': 'fontawesome/brands/github',
+    },
+
+    # Version dropdown
+    'version_dropdown': True,
+    'version_info': [
+        {'version': 'latest', 'title': 'latest', 'aliases': []},
+        # Add more versions as needed
+    ],
+}
+
+# Version dropdown JSON file
+html_context = {
+    "version_json": "https://raw.githubusercontent.com/kubeflow/katib/master/docs/versions.json",
+}
+# Exclude patterns
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
+
+# -- Options for autodoc -------------------------------------------------
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'special-members': '__init__',
+    'undoc-members': True,
+    'exclude-members': '__weakref__'
+}

docs/sdkdocs/source/index.rst

@@ -0,0 +1,20 @@
+.. Kubeflow Katib SDK APIs Reference documentation master file, created by
+   sphinx-quickstart on Sat Aug 10 02:27:22 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Kubeflow Katib SDK APIs Documentation!
+=============================================================
+
+.. mdinclude:: ../../../sdk/python/v1beta1/README.md
+
+.. toctree::
+   :hidden:
+
+   Home <self>
+   src/katib
+   src/models/model
+   Usage Docs (kubeflow.org) <https://www.kubeflow.org/docs/components/katib/>
+   Source Code <https://github.com/kubeflow/katib/>
+
+

docs/sdkdocs/source/src/katib.rst

@@ -0,0 +1,11 @@
+Katib SDK APIs Reference
+========================
+
+.. autoclass:: api.katib_client.KatibClient
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :inherited-members:
+
+   .. automethod:: __init__
+      :no-index:

docs/sdkdocs/source/src/models/model.rst

@@ -0,0 +1,50 @@
+Model Reference index
+----------------------
+
+.. _rst-modules:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Rst Modules:
+
+   v1beta1_algorithm_setting
+   v1beta1_algorithm_spec
+   v1beta1_collector_spec
+   v1beta1_config_map_source
+   v1beta1_early_stopping_rule
+   v1beta1_early_stopping_setting
+   v1beta1_early_stopping_spec
+   v1beta1_experiment_condition
+   v1beta1_experiment_list
+   v1beta1_experiment
+   v1beta1_experiment_spec
+   v1beta1_experiment_status
+   v1beta1_feasible_space
+   v1beta1_file_system_path
+   v1beta1_filter_spec
+   v1beta1_graph_config
+   v1beta1_metric
+   v1beta1_metric_strategy
+   v1beta1_metrics_collector_spec
+   v1beta1_nas_config
+   v1beta1_objective_spec
+   v1beta1_observation
+   v1beta1_operation
+   v1beta1_optimal_trial
+   v1beta1_parameter_assignment
+   v1beta1_parameter_spec
+   v1beta1_source_spec
+   v1beta1_suggestion_condition
+   v1beta1_suggestion_list
+   v1beta1_suggestion
+   v1beta1_suggestion_spec
+   v1beta1_suggestion_status
+   v1beta1_trial_assignment
+   v1beta1_trial_condition
+   v1beta1_trial_list
+   v1beta1_trial
+   v1beta1_trial_parameter_spec
+   v1beta1_trial_source
+   v1beta1_trial_spec
+   v1beta1_trial_status
+   v1beta1_trial_template

docs/sdkdocs/source/src/models/v1beta1_algorithm_setting.rst

@@ -0,0 +1,8 @@
+V1beta1AlgorithmSetting
+=======================
+
+.. automodule:: models.v1beta1_algorithm_setting
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :no-index:

docs/sdkdocs/source/src/models/v1beta1_algorithm_spec.rst

@@ -0,0 +1,8 @@
+V1beta1AlgorithmSpec
+====================
+
+.. automodule:: models.v1beta1_algorithm_spec
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :no-index:

docs/sdkdocs/source/src/models/v1beta1_collector_spec.rst

@@ -0,0 +1,8 @@
+V1beta1CollectorSpec
+====================
+
+.. automodule:: models.v1beta1_collector_spec
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :no-index:

docs/sdkdocs/source/src/models/v1beta1_config_map_source.rst

@@ -0,0 +1,8 @@
+V1beta1ConfigMapSource
+======================
+
+.. automodule:: models.v1beta1_config_map_source
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :no-index:

docs/sdkdocs/source/src/models/v1beta1_early_stopping_rule.rst

@@ -0,0 +1,8 @@
+V1beta1EarlyStoppingRule
+========================
+
+.. automodule:: models.v1beta1_early_stopping_rule
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :no-index: