Merge pull request #2 from optuna/master

Update translation to v2.3

.gitignore

@@ -132,6 +132,15 @@ dmypy.json
 .vscode/
 
 build*
+source/reference/generated/
+source/reference/multi_objective/generated/
+source/reference/visualization/generated/
+source/tutorial/
+
+
+source/locale/zh_CN/LC_MESSAGES/reference/generated/
+source/locale/zh_CN/LC_MESSAGES/reference/multi_objective/generated/
+source/locale/zh_CN/LC_MESSAGES/reference/visualization/generated/
 
 .DS_Store
 

.readthedocs.yml

@@ -15,11 +15,12 @@ sphinx:
 #mkdocs:
 #  configuration: mkdocs.yml
 
-
-formats: all
+formats:
+  all
+  # - htmlzip
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
   version: 3.7
   install:
-    - requirements: requirements.txt
+    - requirements: requirements.txt

Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -W --keep-going
+SPHINXOPTS    = -W --keep-going -Dlanguage='zh_CN'
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = Optuna
 SOURCEDIR     = source
@@ -17,4 +17,12 @@ help:
 # 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)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf source/reference/generated/
+	rm -rf source/reference/multi_objective/generated/
+	rm -rf source/reference/visualization/generated/
+	rm -rf source/tutorial/

README.md

@@ -2,48 +2,44 @@
 
 本仓库为 [Optuna](https://optuna.org) 文档的的简体中文翻译。我们通过 [sphinx-intl](http://sphinx-intl.rtfd.io) 来进行翻译。
 
-
-
 ## Optuna 版本更新后文档更新的步骤
 
 克隆仓库到本地，并创建一个新分支。
 
 安装依赖（这一步推荐在虚拟环境下进行）：
 
-`pip install -r requirements.txt` 
+`pip install -r requirements.txt`
 
 生成当前版本的翻译文件：
 
-`sphinx-intl update -p build/locale -l zh`
+`sphinx-intl update -p build/locale -l zh_CN`
 
-在 `requirements.txt` 中修改Optuna到想要的版本号。
+在 `requirements.txt` 中修改 Optuna 到想要的版本号。
 
 安装新版的 Optuna：
 
 `pip install -r requirements.txt`
 
-
 克隆 Optuna 的[主仓库](https://github.com/optuna/optuna) 到本地。
 
-将 Optuna 的主仓库reset 到你准备更新的版本发布的commit。
-
+将 Optuna 的主仓库 reset 到你准备更新的版本发布的 commit。
 
-将Optuna 主仓库内的 `doc/source` 目录下的除 `config.py` 之外的所有文件拷贝到此仓库的 `source` 目录下，覆盖当前文件。
+将 Optuna 主仓库内的 `doc/source` 目录下的除 `config.py` 之外的所有文件拷贝到此仓库的 `source` 目录下，覆盖当前文件。
 
 更新翻译文件:
 
 `make gettext`
 
-`sphinx-intl update -p build/gettext -l zh`
+`sphinx-intl update -p build/gettext -l zh_CN`
 
 更新翻译
 
-1. 通过gitdiff查看所有 `.po` 文件的变动
+1. 通过 gitdiff 查看所有 `.po` 文件的变动
 2. 对存在变动而且带有 `#, fuzzy` 的行进行修改（注意，通常情况下请忽略每个文件开头的 `#, fuzzy`）
+3. 查看所有的 `msgstr ""` 并对它们进行翻译 （`msgstr ""` 代表需要翻译但是没完成翻译的句子, 但是多行翻译也会存在首行为 `msgstr ""` 的情况，这时不一定代表翻译没完成）
 
 生成更新后的文档的静态网页，检查是否有错：
 
-`make -e SPHINXOPTS="-Dlanguage='zh'" html` 
-
-确认无误后，在当前分支提交修改并创建PR，等待更新被merge到主分支中。
+`make -e SPHINXOPTS="-Dlanguage='zh_CN'" html`
 
+确认无误后，在当前分支提交修改并创建 PR，等待更新被 merge 到主分支中。

requirements.txt

@@ -1,10 +1,13 @@
-optuna==2.0.0
-Sphinx
+optuna==2.3.0
+sphinx==3.0.4
 sphinx-rtd-theme==0.5.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2
 sphinxcontrib-htmlhelp==1.0.3
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.4
-
+sphinx-gallery
+matplotlib
+pillow
+scikit-learn

source/_templates/autosummary/class.rst

@@ -0,0 +1,19 @@
+{% extends "!autosummary/class.rst" %}
+
+{#
+An autosummary template to exclude the class constructor (__init__)
+which doesn't contain any docstring in Optuna.
+#}
+
+{% block methods %}
+   {% set methods = methods | select("ne", "__init__") | list %}
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+
+{% endblock %}

source/conf.py

@@ -16,11 +16,11 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
-import os
 import pkg_resources
 
+from sphinx_gallery.sorting import FileNameSortKey
+
 __version__ = pkg_resources.get_distribution('optuna').version
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 # -- Project information -----------------------------------------------------
 
@@ -44,13 +44,16 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
     'cliff.sphinxext',
+    'sphinx_gallery.gen_gallery',
+    'matplotlib.sphinxext.plot_directive',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -85,17 +88,20 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-if not on_rtd:
-    html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'logo_only': True
+}
 
 html_favicon = '../image/favicon.ico'
 
+html_logo = '../image/optuna-logo.png'
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -141,7 +147,8 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'Optuna.tex', 'Optuna Documentation', 'Optuna Contributors.', 'manual'),
+    (master_doc, 'Optuna.tex', 'Optuna Documentation',
+     'Optuna Contributors.', 'manual'),
 ]
 
 # -- Options for manual page output ------------------------------------------
@@ -163,6 +170,30 @@
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 
 # -- Extension configuration -------------------------------------------------
-# path is example but recommended.
+autosummary_generate = True
+autodoc_default_options = {
+    'members': True,
+    'inherited-members': True,
+    'exclude-members': 'with_traceback',
+}
+
+sphinx_gallery_conf = {
+    'examples_dirs': [
+        '../tutorial',
+    ],
+    'gallery_dirs': [
+        'tutorial',
+    ],
+    'within_subsection_order': FileNameSortKey,
+    'filename_pattern': r'/*\.py',
+    'first_notebook_cell': None,
+}
+
+# matplotlib plot directive
+plot_include_source = True
+plot_formats = [("png", 90)]
+plot_html_show_formats = False
+plot_html_show_source_link = False
+
 locale_dirs = ['locale/']
 gettext_compact = False     # optional.

source/faq.rst

@@ -60,7 +60,8 @@ Below is an example that uses ``lambda``:
     study = optuna.create_study()
     study.optimize(lambda trial: objective(trial, min_x, max_x), n_trials=100)
 
-Please also refer to `sklearn_addtitional_args.py <https://github.com/optuna/optuna/blob/master/examples/sklearn_additional_args.py>`_ example.
+Please also refer to `sklearn_addtitional_args.py <https://github.com/optuna/optuna/blob/master/examples/sklearn_additional_args.py>`_ example,
+which reuses the dataset instead of loading it in each trial execution.
 
 
 Can I use Optuna without remote RDB servers?
@@ -83,7 +84,7 @@ If you want to save and resume studies,  it's handy to use SQLite as the local s
     study = optuna.create_study(study_name='foo_study', storage='sqlite:///example.db')
     study.optimize(objective)  # The state of `study` will be persisted to the local SQLite file.
 
-Please see :ref:`rdb` for more details.
+Please see :ref:`sphx_glr_tutorial_003_rdb.py` for more details.
 
 
 How can I save and resume studies?
@@ -110,7 +111,7 @@ And to resume the study:
     for key, value in study.best_trial.params.items():
         print(f'    {key}: {value}')
 
-If you are using RDBs, see :ref:`rdb` for more details.
+If you are using RDBs, see :ref:`sphx_glr_tutorial_003_rdb.py` for more details.
 
 How to suppress log messages of Optuna?
 ---------------------------------------
@@ -126,7 +127,7 @@ For instance, you can stop showing each trial result as follows:
 
     study = optuna.create_study()
     study.optimize(objective)
-    # Logs like '[I 2018-12-05 11:41:42,324] Finished a trial resulted in value:...' are disabled.
+    # Logs like '[I 2020-07-21 13:41:45,627] Trial 0 finished with value:...' are disabled.
 
 
 Please refer to :class:`optuna.logging` for further details.

source/index.rst

@@ -14,9 +14,25 @@ Key Features
 
 Optuna has modern functionalities as follows:
 
-- :doc:`Lightweight, versatile, and platform agnostic architecture <tutorial/first>`
-- :doc:`Parallel distributed optimization <tutorial/distributed>`
-- :doc:`Pruning of unpromising trials <tutorial/pruning>`
+- :doc:`Lightweight, versatile, and platform agnostic architecture <tutorial/001_first>`
+
+  - Handle a wide variety of tasks with a simple installation that has few requirements. 
+
+- :doc:`Pythonic search spaces <tutorial/002_configurations>` 
+
+  - Define search spaces using familiar Python syntax including conditionals and loops.
+
+- :doc:`Efficient optimization algorithms <tutorial/007_pruning>`
+
+  - Adopt state-of-the-art algorithms for sampling hyper parameters and efficiently pruning unpromising trials.
+
+- :doc:`Easy parallelization <tutorial/004_distributed>`
+
+  - Scale studies to tens or hundreds or workers with little or no changes to the code.
+
+- :doc:`Quick visualization <reference/visualization/index>`
+
+  - Inspect optimization histories from a variety of plotting functions.
 
 Basic Concepts
 --------------

source/installation.rst

@@ -1,7 +1,7 @@
 Installation
 ============
 
-Optuna supports Python 3.5 or newer.
+Optuna supports Python 3.6 or newer.
 
 We recommend to install Optuna via pip: