From e00777f94c4d099196445de8bf190de3496ff9be Mon Sep 17 00:00:00 2001 From: Tim Date: Mon, 27 May 2024 12:59:45 +0200 Subject: [PATCH] further documentation --- documentation/development/documentation.rst | 7 +- documentation/glossary.rst | 2 + documentation/organizers/intro.rst | 1 + documentation/users/intro.rst | 13 ++- documentation/users/python-client.rst | 92 +++++++++++-------- .../users/python-client/ir-datasets.rst | 18 ++++ .../users/python-client/pyterrier.rst | 11 +++ .../users/python-client/tiraclient.rst | 6 ++ 8 files changed, 107 insertions(+), 43 deletions(-) create mode 100644 documentation/users/python-client/ir-datasets.rst create mode 100644 documentation/users/python-client/pyterrier.rst create mode 100644 documentation/users/python-client/tiraclient.rst diff --git a/documentation/development/documentation.rst b/documentation/development/documentation.rst index dd2bd442..013e86f2 100644 --- 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 `_ deactivate A @enduml -.. todo:: + +.. todo:: TODO UMLet ~~~~~~~ -.. todo:: +.. todo:: TODO Deployment diff --git a/documentation/glossary.rst b/documentation/glossary.rst index 8980ed8d..16929834 100644 --- 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 index d4f5b67e..8b6364ae 100644 --- 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 index c84daf03..9bcb420f 100644 --- 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`. \ No newline at end of file + 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>`_ \ No newline at end of file diff --git a/documentation/users/python-client.rst b/documentation/users/python-client.rst index f78b640c..53238105 100644 --- 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 new file mode 100644 index 00000000..30568d9b --- /dev/null +++ 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 \ No newline at end of file diff --git a/documentation/users/python-client/pyterrier.rst b/documentation/users/python-client/pyterrier.rst new file mode 100644 index 00000000..2c0fdb00 --- /dev/null +++ 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 new file mode 100644 index 00000000..07c9a2e7 --- /dev/null +++ b/documentation/users/python-client/tiraclient.rst @@ -0,0 +1,6 @@ +TIRA Client +=========== + +.. autoclass:: tira.tira_client.TiraClient + :members: + :undoc-members: \ No newline at end of file