further documentation

tira-io · May 27, 2024 · e00777f · e00777f
1 parent ca03523
commit e00777f
Show file tree

Hide file tree

Showing 8 changed files with 107 additions and 43 deletions.
diff --git a/documentation/development/documentation.rst b/documentation/development/documentation.rst
@@ -27,7 +27,7 @@ would like to edit and spot the edit-icon in the top right corner:
 
 Creating a new page
 -------------------
-.. todo::
+.. todo:: TODO
 
 
 Glossary
@@ -133,11 +133,12 @@ content. You can find the official documentation `here <https://plantuml.com/>`_
                 deactivate A
 
                 @enduml
-.. todo::
+
+.. todo:: TODO
 
 UMLet
 ~~~~~~~
-.. todo::
+.. todo:: TODO
 
 
 Deployment

diff --git a/documentation/glossary.rst b/documentation/glossary.rst
@@ -1,3 +1,5 @@
+.. _glossary:
+
 Glossary
 ========
 

diff --git a/documentation/organizers/intro.rst b/documentation/organizers/intro.rst
@@ -1,4 +1,5 @@
 .. _orgintropage:
+
 Introduction
 ============
 

diff --git a/documentation/users/intro.rst b/documentation/users/intro.rst
@@ -16,8 +16,17 @@ Getting Started
 
 
 .. _userfaq:
-.. rubric:: Frequently Asked Questions
+Frequently Asked Questions
+--------------------------
+
+.. rubric:: Participation
 
 .. dropdown:: How do I participate in a shared task?
 
-    See :ref:`ParticipatePage`.
+    See :ref:`ParticipatePage`.
+
+.. rubric:: Problems
+
+.. dropdown:: I believe, I found a bug with TIRA. What do I do?
+
+    Please have a look at `Reporting Bugs <../development/contributing/index.html#reporting-bugs>`_
diff --git a/documentation/users/python-client.rst b/documentation/users/python-client.rst
@@ -1,54 +1,70 @@
 Python Client
 =============
-.. todo:: Add a nice introductory text
+For programatic access to TIRA, we provide a python API, the "Python Client", which serves two use-cases:
 
-* :ref:`modindex`
+(1) Interfacing with the TIRA platform
+(2) Integrating with third party APIs (e.g., ir-datasets) that would not work otherwise due to TIRA's sandbox.
 
+.. important:: TIRA sandboxes all the evaluation runs to avoid publicizing evaluation data and maintain comparability
+   beyond the initial shared task. For you, this means that you can't access arbitrary external resources. Since you
+   should not, of course, have to abstain from using `hugging-face`, `ìr_datasets` or other crucial dependencies, we
+   integrated some of these into the sandbox.
 
-tira.io\_utils module
----------------------
+.. toctree::
 
-.. automodule:: tira.io_utils
-   :members:
-   :undoc-members:
-   :show-inheritance:
+   python-client/tiraclient
+   python-client/pyterrier
+   python-client/ir-datasets
 
-tira.ir\_datasets\_util module
-------------------------------
 
-.. automodule:: tira.ir_datasets_util
-   :members:
-   :undoc-members:
-   :show-inheritance:
+..
+   * :ref:`modindex`
 
-tira.pyterrier\_integration module
-----------------------------------
 
-.. automodule:: tira.pyterrier_integration
-   :members:
-   :undoc-members:
-   :show-inheritance:
+   tira.io\_utils module
+   ---------------------
 
-tira.pyterrier\_util module
----------------------------
+   .. automodule:: tira.io_utils
+      :members:
+      :undoc-members:
+      :show-inheritance:
 
-.. automodule:: tira.pyterrier_util
-   :members:
-   :undoc-members:
-   :show-inheritance:
+   tira.ir\_datasets\_util module
+   ------------------------------
 
-tira.third\_party\_integrations module
---------------------------------------
+   .. automodule:: tira.ir_datasets_util
+      :members:
+      :undoc-members:
+      :show-inheritance:
 
-.. automodule:: tira.third_party_integrations
-   :members:
-   :undoc-members:
-   :show-inheritance:
+   tira.pyterrier\_integration module
+   ----------------------------------
 
-Module contents
----------------
+   .. automodule:: tira.pyterrier_integration
+      :members:
+      :undoc-members:
+      :show-inheritance:
 
-.. automodule:: tira
-   :members:
-   :undoc-members:
-   :show-inheritance:
+   tira.pyterrier\_util module
+   ---------------------------
+
+   .. automodule:: tira.pyterrier_util
+      :members:
+      :undoc-members:
+      :show-inheritance:
+
+   tira.third\_party\_integrations module
+   --------------------------------------
+
+   .. automodule:: tira.third_party_integrations
+      :members:
+      :undoc-members:
+      :show-inheritance:
+
+   Module contents
+   ---------------
+
+   .. automodule:: tira
+      :members:
+      :undoc-members:
+      :show-inheritance:
diff --git a/documentation/users/python-client/ir-datasets.rst b/documentation/users/python-client/ir-datasets.rst
@@ -0,0 +1,18 @@
+IR-Datasets Integration
+=======================
+
+The **only** thing you need to know about TIRA's ir_datasets integration as a user is to replace your import of
+ir_datasets like so:
+
+.. code-block:: diff
+    
+   - import ir_datasets
+   + from tira.third_party_integrations import ir_datasets
+
+Now you can work with ir_datasets **exactly** like you usually would. The entire rest of this page only contains
+background information on what happens behind the scenes and you can safely skip it if you are not interested.
+
+
+.. rubric:: Behind the Scenes
+
+.. todo:: TODO
diff --git a/documentation/users/python-client/pyterrier.rst b/documentation/users/python-client/pyterrier.rst
@@ -0,0 +1,11 @@
+Pyterrier Integration
+=====================
+
+.. code-block:: diff
+
+    - import pyterrier as pt
+    - if not pt.started():
+    -     pt.init()
+    + from tira.third_party_integrations import ensure_pyterrier_is_loaded
+    + ensure_pyterrier_is_loaded()
+    + import pyterrier as pt
diff --git a/documentation/users/python-client/tiraclient.rst b/documentation/users/python-client/tiraclient.rst
@@ -0,0 +1,6 @@
+TIRA Client
+===========
+
+.. autoclass:: tira.tira_client.TiraClient
+   :members:
+   :undoc-members: