Docs/references in notebooks (#58)

Author: voorhs

docs/source/concepts.rst

@@ -2,7 +2,30 @@ Key Concepts
 ============
 
 
-- **Optimization Search Space**. Автоматический подбор классификатора происходит за счет перебора гиперпараметров в некотором *пространстве поиска*. Говоря на уровне идеи, это пространство поиска является словариком, в котором ключами являются имена гиперпараметров, а значениями --- списки. Гиперпараметры выступают в роли координатных "осей" пространства поиска, а значения в списках --- в роли точек на этой оси.
-- **Classification Stages**. Классификацию интента можно разделить на два этапа: скоринг и предсказание. Скоринг --- это предсказание вероятностей наличия каждого интента в данной реплике. Предсказание --- это формирование финального предсказания на основе предоставленных вероятностей.
-- **Prediction**. Если мы хотим детектировать out-of-domain примеры, то на этапе предсказания необходимо подобрать порог вероятности, при котором можно утверждать о наличии какого-то известного интента. 
-- **Nodes and Modules**. Модель скоринга или предсказания вместе с её гиперпараметрами, которые нужно перебрать, мы называем *модулем оптимизации*. Набор модулей, относящихся к одному этапу оптимизации (скорингу или предсказанию), мы называем *узлом оптимизации*.
+.. _key-search-space:
+
+Optimization Search Space
+-------------------------
+
+Автоматический подбор классификатора происходит за счет перебора гиперпараметров в некотором *пространстве поиска*. Говоря на уровне идеи, это пространство поиска является словариком, в котором ключами являются имена гиперпараметров, а значениями --- списки. Гиперпараметры выступают в роли координатных "осей" пространства поиска, а значения в списках --- в роли точек на этой оси.
+
+.. _key-stages:
+
+Classification Stages
+---------------------
+
+Классификацию интента можно разделить на два этапа: скоринг и предсказание. Скоринг --- это предсказание вероятностей наличия каждого интента в данной реплике. Предсказание --- это формирование финального предсказания на основе предоставленных вероятностей.
+
+.. _key-oos:
+
+Out-of-domain utterances
+------------------------
+
+Если мы хотим детектировать out-of-domain примеры, то на этапе предсказания необходимо подобрать порог вероятности, при котором можно утверждать о наличии какого-то известного интента. 
+
+.. _key-nodes-modules:
+
+Nodes and Modules
+-----------------
+
+Модель скоринга или предсказания вместе с её гиперпараметрами, которые нужно перебрать, мы называем *модулем оптимизации*. Набор модулей, относящихся к одному этапу оптимизации (скорингу или предсказанию), мы называем *узлом оптимизации*.

docs/source/docs_utils/apiref.py

@@ -98,8 +98,8 @@ class DocumentationLink(ReplacePattern):
     @staticmethod
     def link_to_doc_page(
         page_type: Literal["api", "tutorial", "guide"],
-        page: str,
-        anchor: str | None = None,
+        dotpath: str,
+        obj: str | None = None,
     ) -> str:
         """
         Create a link to a documentation page.
@@ -111,18 +111,18 @@ def link_to_doc_page(
                 - "tutorial" -- Tutorials
                 - "guide" -- User guides
 
-        :param page:
-            Name of the page without the common prefix.
+        :param dotpath:
+            Path to the index page in unix style.
 
-            So, to link to keywords, pass "script.core.keywords" as page (omitting the "chatsky" prefix).
+            So, to link Dataset, pass "context" as page (omitting the "autointent" prefix).
 
             To link to the basic script tutorial, pass "script.core.1_basics" (without the "tutorials" prefix).
 
             To link to the basic concepts guide, pass "basic_conceptions".
 
             API index pages are also supported.
             Passing "index_pipeline" will link to the "apiref/index_pipeline.html" page.
-        :param anchor:
+        :param obj:
             An anchor on the page. (optional)
 
             For the "api" type, use only the last part of the linked object.
@@ -134,12 +134,14 @@ def link_to_doc_page(
             A link to the corresponding documentation part.
         """
         if page_type == "api":
-            prefix = "" if page.startswith("index") else "chatsky."
-            return f"../apiref/{prefix}{page}.rst" + (f"#{prefix}{page}.{anchor}" if anchor is not None else "")
+            path = "/".join(dotpath.split("."))
+            return f"../autoapi/autointent/{path}/index.rst" + (
+                f"#autointent.{dotpath}.{obj}" if obj is not None else ""
+            )
         if page_type == "tutorial":
-            return f"../tutorials/tutorials.{page}.py" + (f"#{anchor}" if anchor is not None else "")
+            return f"../tutorials/tutorials.{dotpath}.py"
         if page_type == "guide":
-            return f"../user_guides/{page}.rst" + (f"#{anchor}" if anchor is not None else "")
+            return f"../guides/{dotpath}.rst" + (f"#{obj}" if obj is not None else "")
         msg = "Unexpected page type"
         raise ValueError(msg)
 

docs/source/docs_utils/notebook.py

@@ -6,7 +6,7 @@ In this section, you will learn how hyperparameter optimization works in our lib
 Pipeline
 --------
 
-The entire process of configuring a classifier in our library is divided into sequential steps:
+The entire process of configuring a classifier in our library is divided into sequential steps (:ref:`and that's why <key-stages>`):
 
 1. Selecting an embedder (EmbeddingNode)
 2. Selecting a classifier (ScoringNode)

docs/source/learn/optimization.rst

@@ -55,7 +55,7 @@ Once the data is ready, you can start building the optimal classifier from the c
 
     autointent data.train_path="path/to/your/data.json"
 
-This command will start the hyperparameter search in the default search space.
+This command will start the hyperparameter search in the default :ref:`search space <key-search-space>`.
 
 As a result, a ``runs`` folder will be created in the current working directory, which will save the selected classifier ready for inference. More about the run folder and what is saved in it can be found in the guide :doc:`guides/optimization_results`.
 
@@ -107,6 +107,7 @@ If there is no need to iterate over pipelines and hyperparameters, you can impor
 Further Reading
 ---------------
 
+- Get familiar with :doc:`concepts`.
 - Learn more about working with data in AutoIntent in our tutorial :doc:`tutorials/index_data`.
 - Learn about how auto-configuration works in our library in the section :doc:`learn/optimization`.
 - Learn more about the search space and how to customize it in the guide :doc:`guides/search_space_configuration`.

docs/source/quickstart.rst

@@ -11,7 +11,7 @@
 from autointent.context.data_handler import Dataset
 
 # %%
-datasets.logging.disable_progress_bar() # disable tqdm outputs
+datasets.logging.disable_progress_bar()  # disable tqdm outputs
 
 # %% [markdown]
 """
@@ -101,9 +101,9 @@
 ```
 
 - `name`: A human-readable representation of the intent.
-- `tags`: Used in multilabel scenarios to predict the most probable class listed in a specific tag.
-- `regexp_partial_match` and `regexp_full_match`: Used by the `RegExp` module to predict intents based on provided patterns.
-- `description`: Used by the `DescriptionScorer` to calculate scores based on the similarity between an utterance and intent descriptions.
+- `tags`: Used in multilabel scenarios to predict the most probable class listed in a specific %mddoclink(api,context.data_handler,Tag).
+- `regexp_partial_match` and `regexp_full_match`: Used by the %mddoclink(api,modules,RegExp) module to predict intents based on provided patterns.
+- `description`: Used by the %mddoclink(api,modules.scoring,DescriptionScorer) to calculate scores based on the similarity between an utterance and intent descriptions.
 
 All fields in the `intents` list are optional except for `id`.
 """
@@ -122,6 +122,8 @@
 # %% [markdown]
 """
 ### Creating a dataset from a Python dictionary
+
+One can load data into Python using our %mddoclink(api,context.data_handler,Dataset) object.
 """
 
 # %%
@@ -203,7 +205,7 @@
 
 # %% [markdown]
 """
-The `Dataset` class organizes your data as a dictionary of splits (`str: datasets.Dataset`).
+The %mddoclink(api,context.data_handler,Dataset) class organizes your data as a dictionary of [datasets.Dataset](https://huggingface.co/docs/datasets/v2.1.0/en/package_reference/main_classes#datasets.Dataset).
 For example, after initialization, an `oos` key may be added if OOS samples are provided.
 In the case of the `banking77` dataset, only the `train` split is available, which you can access as shown below:
 """
@@ -215,7 +217,7 @@
 """
 ### Working with dataset splits
 
-Each split in the `Dataset` class is an instance of [datasets.Dataset](https://huggingface.co/docs/datasets/en/package_reference/main_classes#datasets.Dataset),
+Each split in the %mddoclink(api,context.data_handler,Dataset) class is an instance of [datasets.Dataset](https://huggingface.co/docs/datasets/en/package_reference/main_classes#datasets.Dataset),
 so you can work with them accordingly.
 """
 
@@ -230,7 +232,7 @@
 """
 
 # %%
-dataset.intents[0] # get intent (id=0)
+dataset.intents[0]  # get intent (id=0)
 
 # %% [markdown]
 """
@@ -242,3 +244,11 @@
 
 # %%
 # dataset.push_to_hub("<repo_id>")
+
+# %% [markdown]
+"""
+## See Also
+
+- Training on your data: %mddoclink(tutorial,pipeline_optimization.demo)
+- [Key Concepts](../concepts.html)
+"""