Migrate to MkDocs (#58)

Co-authored-by: Philip Meier <[email protected]>

.gitignore

@@ -162,4 +162,9 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
+
+# MacOS
 **/.DS_Store
+
+# VSCode
+.vscode/

README.md

@@ -1,55 +1,9 @@
 # Ragna
 
-## Local install
+> **Note**
+> This project is in active development.
 
-```bash
-$ conda env create --file environment.yml
-$ conda activate ragna-dev
-$ pip install --editable '.[complete]'
-$ ragna --version
-$ ragna ls
-```
+## Local development
 
-## Minimal example
-
-```python
-import asyncio
-
-from ragna import Rag
-from ragna.assistant import RagnaDemoAssistant
-from ragna.source_storage import RagnaDemoSourceStorage
-
-
-async def main():
-    rag = Rag()
-
-    path = "ragna.txt"
-    with open(path, "w") as file:
-        file.write("Ragna is an OSS RAG app with Python and REST API.\n")
-
-    async with await rag.new_chat(
-        documents=[path],
-        source_storage=RagnaDemoSourceStorage,
-        assistant=RagnaDemoAssistant,
-    ) as chat:
-        print(await chat.answer("What is Ragna?"))
-
-
-# This is only needed when running module as script.
-# If inside a notebook, the code inside the main function can be run directly.
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
-## Documentation
-
-Ragna uses Sphinx to build it's documentation.
-
-You can contribute to the documentation at `docs/source`,
-and start a development build that auto-refreshes on new changes with:
-
-```bash
-sphinx-autobuild docs/source docs/build/html
-```
-
-which serves the docs website at [http://127.0.0.1:8000](http://127.0.0.1:8000).
+* Setup: [docs/community/contribute.md](docs/community/contribute.md)
+* Quickstart: [docs/get-started.md](docs/get-started.md#minimal-example)

docs/community/brand.md

@@ -0,0 +1 @@
+# Brand guidelines

docs/community/contribute.md

@@ -0,0 +1,49 @@
+# Contribute to Ragna
+
+<!-- TODO: expand and add more narration -->
+
+## Fork and clone the repository
+
+```bash
+git clone https://github.com/<your-username>/ragna.git
+```
+
+## Set up development environment
+
+Create and activate a conda environment:
+
+```bash
+conda env create --file environment.yaml
+conda activate ragna-dev
+```
+
+## Contribute code
+
+Install Ragna in editable mode:
+
+```bash
+pip install --editable '.[complete]'
+```
+
+Verify your installation:
+
+```bash
+ragna --version
+ragna ls
+```
+
+## Contribute documentation
+
+Ragna uses MkDocs to build it's documentation.
+
+You can contribute to narrative documentation at `docs/`,
+and configure the docs website using `mkdocs.yml`
+
+To start a development build that auto-refreshes on new changes,
+run the following from the root directory:
+
+```bash
+mkdocs serve
+```
+
+This serves the docs website at [http://127.0.0.1:8000](http://127.0.0.1:8000).

docs/explanations/understand-rag.md

@@ -0,0 +1 @@
+# What is RAG?

docs/get-started.md

@@ -0,0 +1,37 @@
+# Get started
+
+## Installation
+
+<!-- TODO -->
+
+
+## Minimal example
+
+```python
+import asyncio
+
+from ragna import Rag
+from ragna.assistant import RagnaDemoAssistant
+from ragna.source_storage import RagnaDemoSourceStorage
+
+
+async def main():
+    rag = Rag()
+
+    path = "ragna.txt"
+    with open(path, "w") as file:
+        file.write("Ragna is an OSS RAG app with Python and REST API.\n")
+
+    async with await rag.new_chat(
+        documents=[path],
+        source_storage=RagnaDemoSourceStorage,
+        assistant=RagnaDemoAssistant,
+    ) as chat:
+        print(await chat.answer("What is Ragna?"))
+
+
+# This is only needed when running module as script.
+# If inside a notebook, the code inside the main function can be run directly.
+if __name__ == "__main__":
+    asyncio.run(main())
+```

docs/source/index.md → docs/index.md

@@ -1,10 +1,16 @@
-# Ragna
+---
+title: Welcome
+---
 
-<!-- The following description is not final and likely to change. -->
+# Ragna
 
-Ragna is a toolkit for building RAG-based LLM applications.
+A toolkit for building RAG-based LLM applications, it provides:
 
-It provides:
 * **Python API** for RAG orchestration
 * **REST API** for building web applications
 * **Ready-to-use web application** with UI for uploading documents, selecting models, and chat interface.
+
+<!-- TODO:
+- Update description
+- Link to relevant sections of the docs
+-->

docs/references/changelog.md

@@ -0,0 +1 @@
+# Release notes

docs/references/cli.md

@@ -0,0 +1 @@
+# CLI reference

docs/references/python-api.md

@@ -0,0 +1 @@
+# Python API reference

docs/references/rest-api.md

@@ -0,0 +1 @@
+# REST API reference

docs/tutorials/python-api.md

@@ -0,0 +1 @@
+# Use the Python API

docs/tutorials/rest-api.md

@@ -0,0 +1 @@
+# Explore the REST API

docs/tutorials/web-app.md

@@ -0,0 +1 @@
+# Set up a web application

environment.yml

@@ -14,10 +14,6 @@ dependencies:
     - mypy
     - pre-commit
     # documentation
-    - sphinx
-    - myst-parser
-    - sphinx-copybutton
-    - furo
-    - sphinx-design
-    - sphinx-inline-tabs
-    - sphinxext-opengraph
+    - mkdocs
+    - mkdocs-material
+    - mkdocstrings

mkdocs.yml

@@ -0,0 +1,5 @@
+site_name: Ragna
+theme:
+  name: material
+  features:
+    - navigation.sections