docs update (#5)

* description added * usage examples added
catalyst-team · Aug 11, 2021 · f43e751 · f43e751
1 parent c635a3c
commit f43e751
Show file tree

Hide file tree

Showing 10 changed files with 310 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,84 @@
+<img src="docs/_static/slayer.png" align="right">
+
 # Hydra Slayer
 
-Hydra Slayer is a 4th level spell in the School of Fire Magic.
+[![build](https://github.com/catalyst-team/hydra-slayer/actions/workflows/build.yml/badge.svg)](https://github.com/catalyst-team/hydra-slayer/actions/workflows/build.yml)
+[![Pipi version](https://img.shields.io/pypi/v/hydra-slayer)](https://pypi.org/project/hydra-slayer/)
+[![Python Version](https://img.shields.io/pypi/pyversions/hydra-slayer)](https://pypi.org/project/hydra-slayer/)
+[![License](https://img.shields.io/github/license/catalyst-team/hydra-slayer)](LICENSE)
+[![Slack](https://img.shields.io/badge/slack-join_chat-brightgreen.svg)](https://join.slack.com/t/catalyst-team-core/shared_invite/zt-d9miirnn-z86oKDzFMKlMG4fgFdZafw)
+
+**Hydra Slayer** is a 4th level spell in the School of Fire Magic.
 Depending of the level of expertise in fire magic,
 slayer spell increases attack of target troop by 8 against
-hydras, snakes (especially pythons), and other creatures.
+behemoths, dragons, hydras, and other creatures.
+
+What is more, it also allows configuring of complex applications just by config and few lines of code.
+
+---
+
+## Installation
+Using pip you can easily install the latest release version [PyPI](https://pypi.org/):
+
+```sh
+pip install hydra-slayer
+```
+
+## Example
+```yaml title="config.yaml"
+dataset:
+  _target_: torchvision.datasets.CIFAR100
+  root: ./data
+  train: false
+  transform:
+    _target_: torchvision.transforms.Compose
+    transforms:
+      - _target_: torchvision.transforms.ToTensor
+      - _target_: torchvision.transforms.Normalize
+        mean: [0.1307]
+        std: [0.3081]
+  download: true
+```
+
+```python title="run.py"
+import hydra_slayer
+import yaml
+
+registry = hydra_slayer.Registry()
+with open("dataset.yaml") as stream:
+    raw_config = yaml.safe_load(stream)
+
+config = registry.get_from_params(**raw_config)
+config["dataset"]
+# Dataset CIFAR100
+#     Number of datapoints: 10000
+#     Root location: ./data
+#     Split: Test
+#     StandardTransform
+# Transform: Compose(
+#     ToTensor()
+#     Normalize(mean=[0.5, 0.5, 0.5], std=[0.5, 0.5, 0.5])
+# )
+```
+
+Please check [documentation](https://catalyst-team.github.io/hydra-slayer/master/pages/examples) for more examples.
+
+## Documentation
+Full documentation for the project is available at https://catalyst-team.github.io/hydra-slayer
+
+## Communication
+- GitHub Issues: Bug reports, feature requests, install issues, RFCs, thoughts, etc.
+- Slack: The [Catalyst Slack](https://join.slack.com/t/catalyst-team-core/shared_invite/zt-d9miirnn-z86oKDzFMKlMG4fgFdZafw) hosts a primary audience of moderate to experienced Hydra-Slayer (and Catalyst) users and developers for general chat, online discussions, collaboration, etc.
+- Email: Feel free to use [[email protected]](mailto:[email protected]) as an additional channel for feedback.
+
+## Citation
+Please use this bibtex if you want to cite this repository in your publications:
+
+    @misc{catalyst,
+        author = {Sergey Kolesnikov and Yauheni Kachan},
+        title = {Hydra-Slayer},
+        year = {2021},
+        publisher = {GitHub},
+        journal = {GitHub repository},
+        howpublished = {\url{https://github.com/catalyst-team/hydra-slayer}},
+    }
diff --git a/docs/_static/advanced_fire_magic.png b/docs/_static/advanced_fire_magic.png
diff --git a/docs/_static/basic_fire_magic.png b/docs/_static/basic_fire_magic.png
diff --git a/docs/_static/expert_fire_magic.png b/docs/_static/expert_fire_magic.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -8,6 +8,8 @@ Hydra Slayer |version|
     <a class="github-button" href="https://github.com/catalyst-team/hydra-slayer/fork" data-icon="octicon-repo-forked" data-size="large" data-show-count="true" aria-label="Fork leverxgroup/esrgan on GitHub">Fork</a> |
     <a class="github-button" href="https://github.com/catalyst-team/hydra-slayer/issues" data-icon="octicon-issue-opened" data-size="large" data-show-count="true" aria-label="Issue leverxgroup/esrgan on GitHub">Issue</a>
 
+|Build-Status| |PyPI-Version| |Py-Versions| |License| |Slack|
+
 ----
 
 **Hydra Slayer** is a 4th level spell in the School of Fire Magic.
@@ -49,33 +51,78 @@ Depending of the level of expertise in fire magic, slayer spell increases attack
    +---------------------------------+------------------------+
 
 
+Communication
+=============
+
+* GitHub Issues: Bug reports, feature requests, install issues, RFCs, thoughts, etc.
+
+* Slack: The `Catalyst Slack <catalyst_slack_>`_ hosts a primary audience of moderate to experienced Hydra-Slayer
+  (and Catalyst) users and developers for general chat, online discussions, collaboration, etc.
+
+* Email: Feel free to use [email protected] as an additional channel for feedback.
+
+
 GitHub
 ======
 
-The project's GitHub repository can be found `here <https://github.com/catalyst-team/hydra-slayer>`__.
+The project's GitHub repository can be found `here <slayer_>`_.
 Bugfixes and contributions are very much appreciated!
 
 
 License
 =======
 
-``hydra-slayer`` is released under a Apache-2.0 license. See `LICENSE <../LICENSE>`__ for additional details about it.
+``hydra-slayer`` is released under a Apache-2.0 license. See `LICENSE <license_>`_ for additional details about it.
+
+
+Citation
+========
+
+Please use this bibtex if you want to cite this repository in your publications:
+
+.. code-block:: text
+
+   @misc{catalyst,
+      author = {Sergey Kolesnikov and Yauheni Kachan},
+      title = {Hydra-Slayer},
+      year = {2021},
+      publisher = {GitHub},
+      journal = {GitHub repository},
+      howpublished = {\url{https://github.com/catalyst-team/hydra-slayer}},
+   }
 
 .. toctree::
    :maxdepth: 3
    :caption: General
 
    pages/install
-   pages/quickstart
+   pages/examples
 
 .. toctree::
    :maxdepth: 2
    :caption: API
 
    pages/api/registry
    pages/api/factory
+   pages/api/exceptions
 
 Indices and tables
 ==================
 
 :ref:`genindex`
+
+.. _slayer: https://github.com/catalyst-team/hydra-slayer
+.. _slayer_pypi: https://pypi.org/project/hydra-slayer/
+.. _license: ../LICENSE
+.. _catalyst_slack: https://join.slack.com/t/catalyst-team-core/shared_invite/zt-d9miirnn-z86oKDzFMKlMG4fgFdZafw
+.. _catalyst_email: mailto:[email protected]
+.. |Build-Status| image:: https://github.com/catalyst-team/hydra-slayer/actions/workflows/build.yml/badge.svg
+   :target: https://github.com/catalyst-team/hydra-slayer/actions/workflows/build.yml
+.. |PyPI-Version| image:: https://img.shields.io/pypi/v/hydra-slayer
+   :target: `slayer_pypi`_
+.. |Py-Versions| image:: https://img.shields.io/pypi/pyversions/hydra-slayer
+   :target: `slayer_pypi`_
+.. |License| image:: https://img.shields.io/github/license/catalyst-team/hydra-slayer
+   :target: `license`_
+.. |Slack| image:: https://img.shields.io/badge/slack-join_chat-brightgreen.svg
+   :target: `catalyst_slack`_
diff --git a/docs/pages/api/exceptions.rst b/docs/pages/api/exceptions.rst
@@ -1,7 +1,7 @@
 Exceptions
 ==========
 
-<Description>
+Sorry, the person who is responsible for the description was eaten by hydras last week.
 
 
 .. automodule:: hydra_slayer.exceptions

diff --git a/docs/pages/api/factory.rst b/docs/pages/api/factory.rst
@@ -1,7 +1,7 @@
 Factory
 =======
 
-<Description>
+Sorry, the person who is responsible for the description was eaten by hydras last week.
 
 
 .. automodule:: hydra_slayer.factory

diff --git a/docs/pages/api/registry.rst b/docs/pages/api/registry.rst
@@ -1,7 +1,7 @@
 Registry
 ========
 
-<Description>
+Sorry, the person who is responsible for the description was eaten by hydras last week.
 
 
 .. automodule:: hydra_slayer.registry

diff --git a/docs/pages/examples.rst b/docs/pages/examples.rst
@@ -0,0 +1,177 @@
+.. _examples:
+
+========
+Examples
+========
+
+Basic Level
+^^^^^^^^^^^
+
+.. raw:: html
+
+   <div>
+     <img src="../_static/basic_fire_magic.png" style="float: right; padding-left: 24px;" />
+     <p>Create <a href="https://www.cs.toronto.edu/~kriz/cifar.html">CIFAR100</a> dataset from config file with params.</p>
+     <blockquote>Please note that <b>Basic Fire Magic</b> also allows your hero to cast fire spells at reduced cost.</blockquote>
+   </div>
+
+.. code-block:: yaml
+
+   # dataset.yaml
+   _target_: torchvision.datasets.CIFAR100
+   root: ./data
+   train: false
+   transform:
+     _target_: torchvision.transforms.Compose
+     transforms:
+       - _target_: torchvision.transforms.ToTensor
+       - _target_: torchvision.transforms.Normalize
+         mean: [0.1307]
+         std: [0.3081]
+   download: true
+
+.. code-block:: python
+
+   import hydra_slayer
+   import yaml
+
+   registry = hydra_slayer.Registry()
+   with open("dataset.yaml") as stream:
+       config = yaml.safe_load(stream)
+
+   dataset = registry.get_from_params(**config)
+   dataset
+   # Dataset CIFAR100
+   #     Number of datapoints: 10000
+   #     Root location: ./data
+   #     Split: Test
+   #     StandardTransform
+   # Transform: Compose(
+   #     ToTensor()
+   #     Normalize(mean=[0.5, 0.5, 0.5], std=[0.5, 0.5, 0.5])
+   # )
+
+
+Advanced Level
+^^^^^^^^^^^^^^
+
+.. raw:: html
+
+   <div>
+     <img src="../_static/advanced_fire_magic.png" style="float: right; padding-left: 24px;" />
+     <p>Read multiple CSV files as pandas dataframes and merge them.</p>
+     <blockquote>Please note that <b>Advanced Fire Magic</b> also allows your hero to cast fire spells at reduced cost and increased effectiveness.</blockquote>
+   </div>
+
+.. code-block:: yaml
+
+   # dataset.yaml
+   dataframe:
+     _target_: pandas.merge
+     left:
+       _target_: pandas.read_csv
+       filepath_or_buffer: dataset/dataset_part1.csv
+
+       # By default, hydra-slayer use partial fit for functions
+       # (what is useful with activation functions in neural networks).
+       # But if we want to call ``pandas.read_csv`` function instead,
+       # then we should pass ``call_meta_factory`` manually.
+       meta_factory: &call_function
+         _target_: catalyst.tools.registry.call_meta_factory
+     right:
+       _target_: pandas.read_csv
+       filepath_or_buffer: dataset/dataset_part2.csv
+       meta_factory: *call_function
+     how: inner
+     on: user
+     meta_factory: *call_function
+
+.. code-block:: python
+
+   import hydra_slayer
+   import yaml
+
+   registry = hydra_slayer.Registry()
+   with open("config.yaml") as stream:
+       raw_config = yaml.safe_load(stream)
+
+   config = registry.get_from_params(**raw_config)
+
+   dataset = config["dataframe"]
+   dataset
+   # <class 'pandas.core.frame.DataFrame'>
+   #    user country  premium  ...
+   # 0     1     USA     True  ...
+   # 1     2     USA    False  ...
+   #     ...     ...      ...  ...
+
+
+Expert level
+^^^^^^^^^^^^
+
+.. raw:: html
+
+  <div>
+    <img src="../_static/expert_fire_magic.png" style="float: right; padding-left: 24px;" />
+    <p>Sorry, the person who is responsible for the expert level example was eaten by hydras last week.</p>
+    <blockquote>Please note that <b>Expert Fire Magic</b> also allows your hero to cast fire spells at reduced cost and maximum effectiveness.</blockquote>
+  </div>
+
+..
+  .. code-block:: yaml
+
+    # dataset.yaml
+    _target_: torchvision.datasets.CIFAR100
+    root: ./data
+    train: false
+    transform:
+      _target_: torchvision.transforms.Compose
+      transforms:
+        - _target_: torchvision.transforms.ToTensor
+        - _target_: torchvision.transforms.Normalize
+          mean: [0.5,0.5,0.5]
+          std: [0.5,0.5,0.5]
+    download: true
+
+  .. code-block:: yaml
+
+    # config.yaml
+    dataset:
+      _target_: torch.utils.data.DataLoader
+      # TODO: will not work as dict will be retuned, not dataset
+      dataset:
+        # Read dataset from "dataset.yaml", roughly equivalent to
+        # with open("dataset.yaml") as stream:
+        #     params = yaml.safe_load(stream)
+        _target_: yaml.safe_load
+        stream:
+          _target_: open
+          file: dataset_config.yaml
+        meta_factory:
+          _target_: hydra_slayer.call_meta_factory
+      batch_size: 32
+      shuffle: false
+
+    model:
+      _target_: torchvision.models.resnet18
+      pretrained: true
+      meta_factory:
+        _target_: hydra_slayer.call_meta_factory
+
+  .. code-block:: python
+
+    import hydra_slayer
+    import torch
+    import yaml
+
+    registry = hydra_slayer.Registry()
+    with open("config.yaml") as stream:
+        raw_config = yaml.safe_load(stream)
+
+    config = registry.get_from_params(**raw_config)
+    model, dataset = config["model"], config["dataset"]
+
+    model.eval()
+    with torch.no_grad():
+        for batch, y_true in dataset:
+            y_preds = model(batch)