use mkdocs-gallery for example / tutorial documentation

.readthedocs.yml

@@ -12,7 +12,7 @@ build:
 
 mkdocs:
   configuration: mkdocs.yml
-  fail_on_warning: true
+#  fail_on_warning: true
 
 # Optionally declare the Python requirements required to build your docs
 conda:

docs/.gitignore

@@ -0,0 +1 @@
+generated

docs/examples/README.md

@@ -0,0 +1,3 @@
+# Examples
+
+Here are some examples

docs/examples/example_python_api.py

@@ -0,0 +1,31 @@
+"""
+# Python API
+
+"""
+
+# %%
+# Let's create a document
+
+from pathlib import Path
+
+document_path = Path.cwd() / "ragna.txt"
+with open(document_path, "w") as file:
+    file.write("Ragna is awesome!\n")
+
+# %%
+# Let's ask a question
+#
+# !!! note
+#
+#     We can write default markdown here!
+
+from ragna import Rag, assistants, source_storages
+
+rag = Rag()
+async with rag.chat(
+    documents=[document_path],
+    source_storage=source_storages.RagnaDemoSourceStorage,
+    assistant=assistants.RagnaDemoAssistant,
+) as chat:
+    answer = await chat.answer("?")
+print(answer)

environment-dev.yml

@@ -21,3 +21,5 @@ dependencies:
       - mkdocs-gen-files
       - material-plausible-plugin
       - mktestdocs
+      # FIXME: replace this with a stable release when available
+      - mkdocs-gallery @ git+https://github.com/pmeier/mkdocs-gallery@async-gallery

mkdocs.yml

@@ -1,4 +1,5 @@
 site_name: Ragna
+
 repo_url: https://github.com/Quansight/ragna
 copyright: Copyright © 2023 Ragna Development Team at Quansight LLC
 extra:
@@ -54,9 +55,13 @@ plugins:
           import:
             - https://docs.python.org/3/objects.inv
             - https://fastapi.tiangolo.com/objects.inv
-  - gen-files:
-      scripts:
-        - scripts/docs/gen_files.py
+  - gallery:
+      examples_dirs: docs/examples
+      gallery_dirs: docs/generated/gallery
+      filename_pattern: /example_
+  #  - gen-files:
+  #      scripts:
+  #        - scripts/docs/gen_files.py
   - material-plausible
 
 hooks:
@@ -81,6 +86,7 @@ nav:
       - "tutorials/web-app.md"
   - How-to:
       - "how-tos/set-configuration.md"
+  - Examples: generated/gallery
   - Community:
       - "community/welcome.md"
       - "community/contribute.md"

pyproject.toml

@@ -86,9 +86,10 @@ ignore = ["E501"]
 [tool.ruff.per-file-ignores]
 # ignore unused imports and imports not at the top of the file in __init__.py files
 "__init__.py" = ["F401", "E402"]
+# The examples often have imports below the top of the file to follow the narrative
+"docs/examples/**/*.py" = ["E402", "F704"]
 "*.ipynb" = ["E402"]
 
-
 [tool.pytest.ini_options]
 minversion = "6.0"
 addopts = "-ra --tb=short"