diff --git a/.gitignore b/.gitignore index 7990289f..eaa61537 100644 --- a/.gitignore +++ b/.gitignore @@ -14,5 +14,5 @@ tmp/ *.sqlite3 *.db -_build/ - +docs/_build/ +docs/_generated/ diff --git a/README.md b/README.md index f252e289..60bd5ce8 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ You can install optuna-dashboard via [PyPI](https://pypi.org/project/optuna-dash $ pip install optuna-dashboard ``` -Also you can install following optional dependencies to make optuna-dashboard faster. +Also, you can install following optional dependencies to make optuna-dashboard faster. ```console $ pip install optuna-fast-fanova gunicorn diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..42bc2d90 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,173 @@ +/* Parameter names and colons after them in a signature */ +em.sig-param > span:nth-child(1), +em.sig-param > span:nth-child(2) { + color: #555555; +} + +/* Type hints and default values in a signature */ +em.sig-param > span:not(:nth-child(1)):not(:nth-child(2)) { + color: #2980b9; +} + +/* Internal links in a signature */ +.rst-content dl.class > dt a.reference.internal, +.rst-content dl.method > dt a.reference.internal, +.rst-content dl.function > dt a.reference.internal { + color: #2980b9; +} + +/* External links in a signature */ +.rst-content dl.class > dt a.reference.external, +.rst-content dl.method > dt a.reference.external, +.rst-content dl.function > dt a.reference.external { + color: #2980b9; +} + +/* Containers for a signature */ +.rst-content dl.class > dt, +.rst-content dl.function > dt { + background-color: #f0f0f0; +} + +/* Containers for methods, properties, parameters, and returns */ +.rst-content dl:not(.docutils) dl dt { + border-left: solid 3px #6ab0de; +} + +/* Main content */ +.wy-nav-content { + max-width: 1200px; +} + +/* Sidebar header (and topbar for mobile) */ +.wy-side-nav-search, +.wy-nav-top { + background: #f1f3f4; +} +.wy-side-nav-search div.version { + color: #404040; +} + +.wy-nav-top a { + color: #404040; +} + +.wy-nav-top i { + color: #404040; +} + +/* Sidebar */ +.wy-nav-side { + background: #f1f3f4; +} + +/* A tag */ +.wy-menu-vertical a { + color: #707070; +} + +a { + color: #2ba9cd; +} + +.wy-menu-vertical a:active { + background-color: #2ba9cd; + cursor: pointer; + color: #f1f3f4; +} + +.highlight { + background: #f1f3f4; +} + +.navbar { + background: #ffffff; +} + +@media only screen and (max-width: 896px) { + .navbar { + height: 0; + } +} + +.navbar-nav { + background: #ffffff; + list-style: none; + display: flex; + flex-direction: row; + align-items: center; + justify-content: flex-end; + padding: 20px; + max-width: 1200px; + margin-left: 300px; +} + +.ml-auto { + margin-left: auto !important; +} + +.header_link { + margin: 15px 2px; + font-size: 16px; + font-weight: 600; + cursor: pointer; + padding: 0.5rem 0.8rem 0.5rem 0.5rem; + color: #636a73; +} + +.navbar-nav a:focus, +a:hover { + color: #2ba9cd; + text-decoration: none; +} + +.navbar-nav a:visited { + color: #636a73; + text-decoration: none; +} + +.wy-alert.wy-alert-info .wy-alert-title, +.rst-content .note .wy-alert-title, +.rst-content .wy-alert-info.attention .wy-alert-title, +.rst-content .wy-alert-info.caution .wy-alert-title, +.rst-content .wy-alert-info.danger .wy-alert-title, +.rst-content .wy-alert-info.error .wy-alert-title, +.rst-content .wy-alert-info.hint .wy-alert-title, +.rst-content .wy-alert-info.important .wy-alert-title, +.rst-content .wy-alert-info.tip .wy-alert-title, +.rst-content .wy-alert-info.warning .wy-alert-title, +.rst-content .seealso .wy-alert-title, +.rst-content .wy-alert-info.admonition-todo .wy-alert-title, +.rst-content .wy-alert-info.admonition .wy-alert-title, +.wy-alert.wy-alert-info .rst-content .admonition-title, +.rst-content .wy-alert.wy-alert-info .admonition-title, +.rst-content .note .admonition-title, +.rst-content .wy-alert-info.attention .admonition-title, +.rst-content .wy-alert-info.caution .admonition-title, +.rst-content .wy-alert-info.danger .admonition-title, +.rst-content .wy-alert-info.error .admonition-title, +.rst-content .wy-alert-info.hint .admonition-title, +.rst-content .wy-alert-info.important .admonition-title, +.rst-content .wy-alert-info.tip .admonition-title, +.rst-content .wy-alert-info.warning .admonition-title, +.rst-content .seealso .admonition-title, +.rst-content .wy-alert-info.admonition-todo .admonition-title, +.rst-content .wy-alert-info.admonition .admonition-title { + background: #2ba9cd; +} + +.wy-alert, +.rst-content .note, +.rst-content .attention, +.rst-content .caution, +.rst-content .danger, +.rst-content .error, +.rst-content .hint, +.rst-content .important, +.rst-content .tip, +.rst-content .warning, +.rst-content .seealso, +.rst-content .admonition-todo, +.rst-content .admonition { + background: #f1f3f4; +} \ No newline at end of file diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 00000000..1e78869f Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/_static/optuna-logo.png b/docs/_static/optuna-logo.png new file mode 100644 index 00000000..752d6c80 Binary files /dev/null and b/docs/_static/optuna-logo.png differ diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 00000000..3d0314b1 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,40 @@ +.. module:: optuna_dashboard + +API Reference +============= + +General APIs +------------ + +.. autosummary:: + :toctree: _generated/ + :nosignatures: + + optuna_dashboard.run_server + optuna_dashboard.wsgi + optuna_dashboard.set_objective_names + optuna_dashboard.save_note + +Human-in-the-loop +----------------- + +.. autosummary:: + :toctree: _generated/ + :nosignatures: + + optuna_dashboard.register_objective_form_widgets + optuna_dashboard.ObjectiveChoiceWidget + optuna_dashboard.ObjectiveSliderWidget + optuna_dashboard.ObjectiveTextInputWidget + optuna_dashboard.ObjectiveUserAttrRef + +Artifact +-------- + +.. autosummary:: + :toctree: _generated/ + :nosignatures: + + optuna_dashboard.artifact.upload_artifact + optuna_dashboard.artifact.file_system.FileSystemBackend + optuna_dashboard.artifact.boto3.Boto3Backend diff --git a/docs/conf.py b/docs/conf.py index 93077d88..45cbf296 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,26 +2,45 @@ # # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import os +import sys # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'Optuna Dashboard' -copyright = '2023, Masashi Shibata' -author = 'Masashi Shibata' +project = "Optuna Dashboard" +copyright = "2023, Optuna Dashboard Contributors" +author = "Masashi Shibata" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +SOURCE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__name__))) +sys.path.insert(0, SOURCE_DIR) -templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.doctest", + "sphinx.ext.autosummary", +] +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +autosummary_generate = True +autodoc_typehints = "description" +autodoc_default_options = { + "members": True, + "inherited-members": True, + "exclude-members": "with_traceback", +} # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'alabaster' -html_static_path = ['_static'] +html_theme = "sphinx_rtd_theme" +html_theme_options = {"logo_only": True, "navigation_with_keys": True} +html_static_path = ["_static"] +html_favicon = "_static/favicon.ico" +html_logo = "_static/optuna-logo.png" +html_css_files = ["css/custom.css"] diff --git a/docs/index.rst b/docs/index.rst index c8a1d330..996621bc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,15 +3,25 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Optuna Dashboard's documentation! -============================================ +Optuna Dashboard +================ + +Real-time dashboard for `Optuna `_. .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :caption: Contents: + installation + api +Links +===== + +* `Github `_ +* `PyPI `_ + Indices and tables ================== diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..c8fb2ac1 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,17 @@ +Installation +============ + +Optuna Dashboard supports Python 3.7 or newer. + +We recommend to install Optuna via pip: +You can install optuna-dashboard via `PyPI `_ or `Anaconda Cloud `_. + +.. code-block:: console + + $ pip install optuna-dashboard + +Also, you can install following optional dependencies to make optuna-dashboard faster. + +.. code-block:: console + + $ pip install optuna-fast-fanova gunicorn diff --git a/requirements.txt b/requirements.txt index 57ecdd36..25c37877 100644 --- a/requirements.txt +++ b/requirements.txt @@ -17,3 +17,7 @@ moto[s3] # visual regression tests pyppeteer + +# docs +sphinx +sphinx_rtd_theme