Merge pull request #86 from y0z/feature/fix-tutorial

Update documents, tutorials, and examples.

.github/workflows/header-confirm.yaml

@@ -17,4 +17,4 @@ jobs:
       - name: Install dependencies
         run: pip install python-frontmatter
       - name: Confirm headers
-        run: python optunahub-registry/header_confirm.py        
+        run: python optunahub-registry/header_confirm.py

CONTRIBUTING.md

@@ -10,6 +10,14 @@ Please adhere to the following coding standards and guidelines:
 - write your code comments and documentation in English
 - give your package an appropriate name, the package name may be requested to be changed at the discretion of the maintainers
 
+All files must pass linter and formetter checks to be merged to the optunahub-registry repository.
+You can check them by running the [pre-commit](https://pre-commit.com/) tool as follows.
+
+```bash
+pip install pre-commit
+pre-commit install
+pre-commit run  # This will run all checks against currently staged files.
+```
 
 ## Creating a Pull Request
 
@@ -29,6 +37,10 @@ Second, the **description** of your pull request should:
 
 Finally, read [`contributor agreements`](#contributor-agreements) and if you agree, please click the checkbox
 
+## Tutorial
+
+You can find tutorials to implement a package for the OptunaHub registry in [the OptunaHub registry documentation](https://optuna.github.io/optunahub-registry/).
+
 
 ## Contributor Agreements
 

recipes/001_first.py

@@ -111,14 +111,16 @@ def objective(trial: optuna.trial.Trial) -> float:
 
 ###################################################################################################
 # We can see that ``x`` value found by Optuna is close to the optimal value ``2``.
-#
-# In the next recipe, we will show how to register your sampler to OptunaHub.
-# Let's move on to :doc:`002_registration`.
-
 
 ###################################################################################################
 # In the above examples, search space is estimated at the first trial and updated dynamically through optimization.
-# If you pass the search space to the sampler, you can avoid the overhead of estimating the search space.
+# If your sampler requires the search space to be fixed before optimization, you can pass the search space to the sampler at initialization.
+# Passing the search space also allows the sampler to avoid the overhead of estimating the search space.
 sampler = MySampler({"x": optuna.distributions.FloatDistribution(-10, 10)})
 study = optuna.create_study(sampler=sampler)
 study.optimize(objective, n_trials=100)
+
+###################################################################################################
+# In the next recipe, we will show how to register your sampler to OptunaHub.
+# Let's move on to :doc:`002_registration`.
+# See `the User-Defined Sampler documentation <https://optuna.readthedocs.io/en/stable/tutorial/20_recipes/005_user_defined_sampler.html>`_ for more information to implement a sampler.

recipes/002_registration.py

@@ -14,14 +14,15 @@
 | `package <https://github.com/optuna/optunahub-registry/tree/main/package>`__
 | └── category (e.g. samplers, pruners, and visualization)
 |     └── YOUR_PACKAGE_NAME (you need to create this directory and its contents)
-|         ├── README.md
+|         ├── YOUR_ALGORITHM_NAME.py
 |         ├── __init__.py
+|         ├── README.md
 |         ├── LICENSE
-|         ├── (images)
-|         │   ├──  (thumbnail.png)
-|         │   └──  (screenshot.png)
+|         ├── (example.py)
 |         ├── (requirements.txt)
-|         └── YOUR_ALGORITHM_NAME.py
+|         └── (images)
+|             ├──  (thumbnail.png)
+|             └──  (screenshot.png)
 
 An implemented algorithm should be put in the corresponding directory, e.g., a sampler should be put in the `samplers` directory.
 In the `samplers` directory, you should create a directory with a unique identifier.
@@ -31,12 +32,22 @@
 
 The created directory should include the following files:
 
-- `README.md`: A description of your algorithm. This file is used to create an `web page of OptunaHub <https://hub.optuna.org/>`_. Let me explain the format of the `README.md` file later.
+- `YOUR_ALGORITHM_NAME.py`: The implementation of your algorithm.
 - `__init__.py`: An initialization file. This file must implement your algorithm or import its implementation from another file, e.g., `YOUR_ALGORITHM_NAME.py`.
+- `README.md`: A description of your algorithm. This file is used to create an `web page of OptunaHub <https://hub.optuna.org/>`_. Let me explain the format of the `README.md` file later.
 - `LICENSE`: A license file. This file must contain the license of your algorithm. It should be the MIT license in the alpha version of OptunaHub.
-- `images`: This is optional. A directory that contains images. The images in this directory will be used the `web page of OptunaHub <https://hub.optuna.org/>`_. `thumbnail.png` will be used as a thumbnail in the web page. Note that `README.md` can also refer to image files, e.g. `images/screenshot.png`,  in this directory.
+- `example.py`: This is optional. This file should contain a simple example of how to use your algorithm (Example: `example.py for Simulated Annealing Sampler <https://github.com/optuna/optunahub-registry/blob/main/package/samplers/simulated_annealing/example.py>`_).
 - `requirements.txt`: This is optional. A file that contains the additional dependencies of your algorithm. If there are no additional dependencies other than Optuna and OptunaHub, you do not need to create this file.
-- `YOUR_ALGORITHM_NAME.py`: The implementation of your algorithm.
+- `images`: This is optional. A directory that contains images. The images in this directory will be used the `web page of OptunaHub <https://hub.optuna.org/>`_. `thumbnail.png` will be used as a thumbnail in the web page. Note that `README.md` can also refer to image files, e.g. `images/screenshot.png`,  in this directory.
+
+All files must pass linter and formetter checks to be merged to the optunahub-registry repository.
+You can check them by running the `pre-commit <https://pre-commit.com/>`__ tool as follows.
+
+.. code-block:: bash
+
+    pip install pre-commit
+    pre-commit install
+    pre-commit run  # This will run all checks against currently staged files.
 
 `README.md` must contain the following sections:
 
@@ -58,7 +69,7 @@
   - `description`: A brief description of the package. It should be a one-sentence summary of the package.
   - `tags`: The package tags. It should be a list of strings. The tags must include `sampler` or `visualization` depending on the type of the package. You can add other tags as needed. For example, "['sampler', 'LLM']".
   - `optuna_versions`: A list of Optuna versions that the package supports. It should be a list of strings. For example, "['3.5.0', '3.6.1']".
-  - `license`: The license of the package. It should be a string. For example, `'MIT License'`. The license must be `MIT` in the alpha version of OptunaHub.
+  - `license`: The license of the package. It should be a string. For example, `'MIT License'`. The license must be `MIT License` in the current version of OptunaHub.
 
 - `Class or Function Names` section that describes the classes or functions provided by the package. If you provide multiple classes or functions, you should list them in this section. Note that the section must be a markdown list. If you provide only one class or function, you can simply write the class or function name. Note that the documentation of the classes or functions must be written in their docstrings. If you want to refer to the documentation, please leave the source code link, or write them in the following `Others` section. For example:
 

recipes/003_pruner.py

@@ -81,3 +81,4 @@ def objective(trial: optuna.trial.Trial) -> float:
 ###################################################################################################
 # After implementing your own pruner, you can register it with OptunaHub.
 # See :doc:`002_registration` for how to register your pruner with OptunaHub.
+# See `the User-Defined Pruner documentation <https://optuna.readthedocs.io/en/stable/tutorial/20_recipes/006_user_defined_pruner.html>`_ for more information to implement an pruner.

template/README.md

@@ -1,23 +1,57 @@
 ---
-author: Please fill in the author name here.
-title: Please fill in the title of the feature here.
-description: Please fill in the description of the feature here.
-tags: Please fill in the list of tags here.
-optuna_versions: Please fill in the versions of Optuna in which you have confirmed the feature works.
-license: Please fill in the license name here. 
+author: "Please fill in the author name here."
+title: "Please fill in the title of the feature here."
+description: "Please fill in the description of the feature here."
+tags: ["Please fill in the list of tags here."]
+optuna_versions: ["Please fill in the list of versions of Optuna in which you have confirmed the feature works, e.g., 3.6.1."]
+license: "MIT License"
 ---
 
+<!--
+This is an example of the frontmatters.
+
+---
+author: "Optuna team"
+title: "My Sampler"
+description: "A description for My Sampler."
+tags: ["sampler", "2nd tag for My Sampler", "3rd tag for My Sampler"]
+optuna_versions: ["3.5.0", "3.6.1"]
+license: "MIT License"
+---
+-->
+
 Please read the [tutorial guide](https://optuna.github.io/optunahub-registry/recipes/001_first.html) to register your feature in OptunaHub.
 You can find more detailed explanation of the following contents in the tutorial.
+Looking at [other packages' implementations](https://github.com/optuna/optunahub-registry/tree/main/package) will also help you.
 
 ## Class or Function Names
-Please fill in the class/function name which you implement here. 
+Please fill in the class/function name which you implement here.
 
 ## Installation
 If you have additional dependencies, please fill in the installation guide here.
+If no additional dependencies is required, this section can be removed.
 
 ## Example
 Please fill in the code snippet to use the implemented feature here.
 
 ## Others
-Please fill in any other information if you have here.
+Please fill in any other information if you have here by adding child sections (###).
+If there is no additional information, this section can be removed.
+
+<!--
+For example, you can add sections to introduce a corresponding paper.
+
+### Reference
+Takuya Akiba, Shotaro Sano, Toshihiko Yanase, Takeru Ohta, and Masanori Koyama. 2019.
+Optuna: A Next-generation Hyperparameter Optimization Framework. In KDD.
+
+### Bibtex
+```
+@inproceedings{optuna_2019,
+    title={Optuna: A Next-generation Hyperparameter Optimization Framework},
+    author={Akiba, Takuya and Sano, Shotaro and Yanase, Toshihiko and Ohta, Takeru and Koyama, Masanori},
+    booktitle={Proceedings of the 25th {ACM} {SIGKDD} International Conference on Knowledge Discovery and Data Mining},
+    year={2019}
+}
+```
+-->