DOC: add documentation

.gitignore

@@ -1,3 +1,5 @@
+*.DS_Store
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

AI_POLICY.md

@@ -1,12 +1,13 @@
 # Usage of Generative AI
 
-The sequince maintainers welcome contributions, including those developed with the assistance of generative AI tools. However, the use of such tools does not change our expectations for contributor responsibility, engagement, or code quality. The following apply to all contributions.
+The Sequince maintainers welcome contributions, including those developed with the assistance of generative AI tools. However, the use of such tools does not change our expectations for contributor responsibility, engagement, or code quality. The following apply to all contributions.
 
 1. **Human ownership and accountability**
-    i. Contributors are responsible for all submitted content, regardless of whether generative AI tools were used.
-    ii. Contributors must be able to explain and justify all changes during review.
-    iii. Contributors are responsible for ensuring all submitted code complies with Sequince's licensing requirements, regardless of whether generative AI tools were used.
-    iv. Contributors must remain the clear human owner of the contribution. Pull requests submitted primarily by automated systems or where no accountable human author is evident may be closed at the maintainers' discretion.
+   We require that:
+    - Contributors are responsible for all submitted content, regardless of whether generative AI tools were used.
+    - Contributors must be able to explain and justify all changes during review.
+    - Contributors are responsible for ensuring all submitted code complies with Sequince's licensing requirements, regardless of whether generative AI tools were used.
+    - Contributors must remain the clear human owner of the contribution. Pull requests submitted primarily by automated systems or where no accountable human author is evident may be closed at the maintainers' discretion.
 
 2. **Engagement**
    The pull request process is collaborative and iterative. Contributors are expected to actively engage with reviewer feedback themselves. Contributors are expected to understand the changes they are proposing, not act as a message courier for a third party.
@@ -20,5 +21,6 @@ The sequince maintainers welcome contributions, including those developed with t
 5. **Maintainer discretion**
    Maintainers may close or decline pull requests that are low quality, excessively burdensome to review, appear to lack meaningful human oversight, or otherwise are not in the best interests of the project.
 
-> [!NOTE]
+> **Note:**
+>
 > This policy is informed by similar guidance adopted in the Scientific Python ecosystem, including Astropy, Matplotlib, and scikit-learn.

CONTRIBUTING.md

@@ -8,10 +8,12 @@ workflow and conventions we use to keep changes easy to review and maintain.
 
 Treat other contributors with respect and follow the
 [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).
-Contributions must comply with the project's [license](LICENSE). Preserve required
+Contributions must comply with the project's
+[license](https://github.com/sequince-dev/sequince/blob/main/LICENSE). Preserve required
 attribution when incorporating third-party material.
 
-AI-assisted contributions are welcome under our [AI policy](AI_POLICY.md).
+AI-assisted contributions are welcome under our
+[AI policy](https://github.com/sequince-dev/sequince/blob/main/AI_POLICY.md).
 Contributors are responsible for understanding, validating, and explaining their
 changes, including their numerical correctness and performance.
 
@@ -157,6 +159,22 @@ def particle_mean(particles: Array) -> Array:
     return xp.mean(particles, axis=0)
 ```
 
+## Building the documentation
+
+The documentation uses Sphinx and lives in `docs/`. From the repository root,
+build the HTML documentation with the dedicated Pixi environment:
+
+```bash
+pixi run -e docs docs
+```
+
+Pixi installs the documentation dependencies defined in `pyproject.toml` when
+preparing this environment. Open `docs/_build/html/index.html` in a browser to
+review the result. Rebuild after editing documentation or API docstrings.
+
+The developer guide embeds this file and `AI_POLICY.md` using MyST. Edit the
+root Markdown files to update their content on GitHub and in the documentation.
+
 ## Checks and tests
 
 Run the following checks before requesting review:

docs/.gitignore

@@ -0,0 +1 @@
+autoapi/

docs/Makefile

@@ -0,0 +1,22 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help docs Makefile
+
+docs: html
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)