Merge pull request #23 from naist-nlp/yaml_docs

Add documents of YAML configuration

README.rst

@@ -81,6 +81,9 @@ This example regards the hypothesis set as the pseudo-reference set.
       --metric.model Unbabel/wmt22-comet-da \
       --metric.batch_size 64 --metric.fp16 true
 
+You can pass the arguments using a configuration yaml file via :code:`--config_path` option.
+See `docs <https://mbrs.readthedocs.io/en/latest/yaml_config.html>`_ for the details.
+
 Finally, you can evaluate the score with :code:`mbrs-score`:
 
 .. code:: bash

docs/cli.rst

@@ -46,6 +46,11 @@ This example regards the hypothesis set as the pseudo-reference set.
       --metric.model Unbabel/wmt22-comet-da \
       --metric.batch_size 64 --metric.fp16 true
 
+.. seealso::
+
+   :doc:`YAML Configuration <./yaml_config>`
+        Passing arguments via a configuration yaml file.
+
 Finally, you can evaluate the score with :code:`mbrs-score`:
 
 .. code:: bash

docs/conf.py

@@ -51,7 +51,6 @@
 
 # html_theme = 'alabaster'
 html_theme = "sphinx_book_theme"
-html_static_path = ["_static"]
 html_logo = "icon.svg"
 html_favicon = "icon.svg"
 html_theme_options = {

docs/index.rst

@@ -12,8 +12,9 @@ mbrs: A library for MBR decoding
       :class-card: sd-border-0
 
       - :doc:`installation`
-      - :doc:`cli`
       - :doc:`api_python`
+      - :doc:`cli`
+      - :doc:`yaml_config`
       - :doc:`tips`
 
    .. grid-item-card:: :material-regular:`list_alt;2em` Implementation lists
@@ -41,8 +42,9 @@ mbrs: A library for MBR decoding
    :hidden:
 
    installation
-   cli
    api_python
+   cli
+   yaml_config
    tips
 
 .. toctree::

docs/yaml_config.rst

@@ -0,0 +1,64 @@
+YAML Configuration
+==================
+
+Command-line arguments can be passed by a configuration yaml file via :code:`--config_path`.
+
+.. seealso::
+
+   :doc:`Command-line interface <./cli>`
+        Overview of the command-line interface.
+
+This is an example of COMET-MBR.
+:code:`hypotheses.txt` are also used as the pseudo-references.
+
+.. code-block:: bash
+
+    mbrs-decode \
+      hypotheses.txt \
+      --num_candidates 1024 \
+      --nbest 1 \
+      --source sources.txt \
+      --references hypotheses.txt \
+      --output translations.txt \
+      --report report.txt --report_format tsv \
+      --decoder mbr \
+      --metric comet \
+      --metric.model Unbabel/wmt22-comet-da \
+      --metric.batch_size 64 --metric.fp16 true
+
+All arguments can be passed via :code:`--config_path`,
+
+.. code-block:: bash
+
+   mbrs-decode --config_path comet_mbr.yaml
+
+with a configuration yaml:
+
+.. code-block:: yaml
+   :caption: comet_mbr.yaml
+
+   common:
+     hypotheses: hypotheses.txt
+     num_candidates: 1024
+     nbest: 1
+     source: sources.txt
+     references: hypotheses.txt
+     output: translations.txt
+     report: report.txt
+     report_format: tsv
+     decoder: mbr
+     metric: comet
+
+   metric:
+     model: Unbabel/wmt22-comet-da
+     batch_size: 64
+     fp16: true
+
+The arguments with dot-prefixes are loaded from each key in the yaml, and others are loaded from the :code:`common:` key.
+In other words, :code:`--metric.` and :code:`--decoder.` are loaded from each corresponding key in the yaml, i.e., :code:`metric:` or :code:`decoder:`.
+
+Of course, you can override the values via command-line arguments, for example:
+
+.. code-block:: bash
+
+   mbrs-decode --config_path comet_mbr.yaml --nbest 1024

mbrs/decoders/probabilistic_mbr.py

@@ -17,7 +17,7 @@
 
 @register("probabilistic_mbr")
 class DecoderProbabilisticMBR(DecoderMBR):
-    """Probablistic MBR decoder using alternating least squares (ALS) approximation.
+    """Probabilistic MBR decoder using alternating least squares (ALS) approximation.
 
     References:
         F. Trabelsi et al., 2024,