docs: Link to how-to doc from index page (#1032)

* docs: Link to how-to doc from index page

Closes #1030:

* Fix samples

* Fix header

* Update ruff.toml

README.md

@@ -44,10 +44,12 @@
   </a>
 </div>
 
-A client to the [LimeSurvey Remote Control API 2](https://manual.limesurvey.org/RemoteControl_2_API), written in modern
-Python.
+*A client to the [LimeSurvey Remote Control API 2](https://manual.limesurvey.org/RemoteControl_2_API), written in modern Python.*
+
 </div>
 
+<!-- begin-short -->
+
 ## Features
 
 - Supports the full RPC API via the [`Session` class](https://citric.readthedocs.io/en/latest/_api/citric/session/index.html#citric.session.Session).
@@ -58,16 +60,14 @@ Python.
 
 ### Integration tests
 
-<!-- start integration status -->
-| | **PostgreSQL** | **MySQL** |
-| - |:--: | :-: |
-| 6.3.4  | ✅ | ✅ |
-| 6.3.3  | ✅ | ✅ |
-| 6.3.1  | ✅ | ✅ |
-| 5.6.44 | ✅ | ✅ |
-| 5.6.43 | ✅ | ✅ |
-| 5.6.42 | ✅ | ✅ |
-<!-- end integration status -->
+Integration tests are run against a LimeSurvey instance, and both PostgreSQL and MySQL backends, using Docker Compose. The following versions of LimeSurvey were tested for this release:
+
+- [6.3.4](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.3.4%2B231108)
+- [6.3.3](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.3.3%2B231106)
+- [6.3.1](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.3.1%2B231023)
+- [5.6.44](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.44%2B231107)
+- [5.6.43](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.43%2B231030)
+- [5.6.42](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.42%2B231024)
 
 ## Installation
 
@@ -95,6 +95,8 @@ for survey in client.list_surveys():
     print(survey["surveyls_title"])
 ```
 
+<!-- end-short -->
+
 ## Documentation
 
 Code samples and API documentation are available at [citric.readthedocs.io](https://citric.readthedocs.io/).

code_samples/auth_plugin.py

@@ -0,0 +1,14 @@
+"""Example of using an auth plugin."""
+
+from __future__ import annotations
+
+# start example
+from citric import Client
+
+client = Client(
+    "https://example.com/index.php/admin/remotecontrol",
+    "iamadmin",
+    "secret",
+    auth_plugin="AuthLDAP",
+)
+# end example

code_samples/context_manager.py

@@ -0,0 +1,13 @@
+"""Example of using the context manager to automatically clean up the session key."""
+
+from __future__ import annotations
+
+# start example
+from citric import Client
+
+LS_URL = "http://localhost:8001/index.php/admin/remotecontrol"
+
+with Client(LS_URL, "iamadmin", "secret") as client:
+    # Do stuff with the client
+    ...
+# end example

code_samples/custom_requests_session.py

@@ -0,0 +1,24 @@
+"""Example of using a custom requests.Session object with the client."""
+
+from __future__ import annotations
+
+# start example
+import requests_cache
+from citric import Client
+
+cached_session = requests_cache.CachedSession(
+    expire_after=60,
+    allowable_methods=["POST"],
+)
+
+client = Client(
+    "https://example.com/index.php/admin/remotecontrol",
+    "iamadmin",
+    "secret",
+    requests_session=cached_session,
+)
+
+# Get all surveys from user "iamadmin".
+# All responses will be cached for 1 minute.
+surveys = client.list_surveys("iamadmin")
+# end example

code_samples/duckdb_sql.py

@@ -0,0 +1,31 @@
+"""Export survey responses to a DuckDB database."""
+
+from __future__ import annotations
+
+# ruff: noqa: I001, PTH123
+
+# start example
+import citric
+import duckdb
+
+client = citric.Client(
+    "https://mylimeserver.com/index.php/admin/remotecontrol",
+    "iamadmin",
+    "secret",
+)
+
+with open("responses.csv", "wb") as file:
+    file.write(client.export_responses(12345, file_format="csv"))
+
+duckdb.execute("CREATE TABLE responses AS SELECT * FROM 'responses.csv'")
+duckdb.sql(
+    """
+    SELECT
+        token,
+        submitdate - startdate AS duration
+    FROM responses
+    ORDER BY 2 DESC
+    LIMIT 10
+"""
+).show()
+# end example

code_samples/get_surveys.py

@@ -0,0 +1,24 @@
+"""Get all surveys and questions from user "iamadmin"."""
+
+# ruff: noqa: T201
+
+from __future__ import annotations
+
+# start example
+from citric import Client
+
+LS_URL = "http://localhost:8001/index.php/admin/remotecontrol"
+
+client = Client(LS_URL, "iamadmin", "secret")
+
+# Get all surveys from user "iamadmin"
+surveys = client.list_surveys("iamadmin")
+
+for s in surveys:
+    print(s["surveyls_title"])
+
+    # Get all questions, regardless of group
+    questions = client.list_questions(s["sid"])
+    for q in questions:
+        print(q["title"], q["question"])
+# end example

code_samples/pandas_df.py

@@ -0,0 +1,27 @@
+"""Export survey responses to a Pandas DataFrame."""
+
+from __future__ import annotations
+
+# ruff: noqa: PD901, S106
+# start example
+import io
+
+import pandas as pd
+from citric import Client
+
+survey_id = 123456
+
+client = Client(
+    "https://mylimeserver.com/index.php/admin/remotecontrol",
+    "iamadmin",
+    "secret",
+)
+
+# Export responses to CSV and read into a Pandas DataFrame
+df = pd.read_csv(
+    io.BytesIO(client.export_responses(survey_id, file_format="csv")),
+    delimiter=";",
+    parse_dates=["datestamp", "startdate", "submitdate"],
+    index_col="id",
+)
+# end example

code_samples/ruff.toml

@@ -0,0 +1,8 @@
+extend = "../pyproject.toml"
+ignore = [
+  "INP001", # implicit-namespace-package
+]
+
+[lint.isort]
+known-first-party = []
+known-third-party = ["citric"]

code_samples/session_attr.py

@@ -0,0 +1,16 @@
+"""Example of using the Client.session attribute to call RPC methods directly."""
+
+from __future__ import annotations
+
+from citric import Client
+
+# start example
+client = Client(
+    "https://mylimeserver.com/index.php/admin/remotecontrol",
+    "iamadmin",
+    "secret",
+)
+
+# Call the copy_survey method, not available in Client
+new_survey_id = client.session.copy_survey(35239, "copied_survey")
+# end example

code_samples/upload_s3.py

@@ -0,0 +1,26 @@
+"""Upload survey files to S3."""
+
+from __future__ import annotations
+
+# start example
+import boto3
+from citric import Client
+
+s3 = boto3.client("s3")
+
+client = Client(
+    "https://mylimeserver.com/index.php/admin/remotecontrol",
+    "iamadmin",
+    "secret",
+)
+
+survey_id = 12345
+
+# Get all uploaded files and upload them to S3
+for file in client.get_uploaded_file_objects(survey_id):
+    s3.upload_fileobj(
+        file.content,
+        "my-s3-bucket",
+        f"uploads/sid={survey_id}/qid={file.meta.question.qid}/{file.meta.filename}",
+    )
+# end example

docs/conf.py

@@ -29,6 +29,8 @@
     "notfound.extension",
 ]
 
+myst_heading_anchors = 2
+
 autodoc_typehints = "description"
 autodoc_typehints_description_target = "documented"