Refactor documentation formatting and enhance installation instructions

docs/api.md

@@ -1,8 +1,10 @@
 # API Reference
 
-All public routines are exported via the `sdepack` Python module. Only
-subroutines declared in the `src/sdepack.pyf` interface file are accessible
-from Python.
+`sdepack` provides a Python interface to a high-performance Fortran numerical
+core compiled via `f2py`. All public routines are exported through the
+`sdepack` module; only subroutines declared in the `src/sdepack.pyf`
+interface file are accessible from Python. See the [Theory](theory.md) and
+[Quickstart](quickstart.md) for mathematical background and usage.
 
 ---
 

docs/installation.md

@@ -1,61 +1,69 @@
 # Installation
 
-`sdepack` is distributed as a compiled wheel on PyPI and can also be installed
-from source via GitHub.
+`sdepack` can be installed from PyPI, conda-forge, or directly from git.
 
----
+## [PyPI](https://pypi.org/project/sdepack)
 
-## Prerequisites
+For using the PyPI package in your project, you can update your configuration file by adding
+the following snippet.
 
-- **Python 3.10+**
-- **NumPy** (installed automatically as a dependency)
+=== "pyproject.toml"
 
-For source builds you additionally need:
+    ```toml
+    [project.dependencies]
+    sdepack = "*" # (1)!
+    ```
 
-- A Fortran compiler (`gfortran` recommended)
-- `meson` and `meson-python` build system
-- `numpy` (for `f2py` compilation)
+    1. Specifying a version is recommended
 
-## PyPI (recommended)
+=== "requirements.txt"
+
+    ```
+    sdepack>=0.1.0
+    ```
 
 ### pip
 
-```bash
-pip install --upgrade sdepack
-```
+=== "Installation for user"
 
-### pyproject.toml dependency
+    ```bash
+    pip install --upgrade --user sdepack # (1)!
+    ```
 
-```toml
-[project]
-dependencies = [
-    "sdepack"
-]
-```
+    1. You may need to use `pip3` instead of `pip` depending on your Python installation.
 
-### requirements.txt
+=== "Installation in virtual environment"
 
-```text
-sdepack
-```
+    ```bash
+    python -m venv .venv
+    source .venv/bin/activate
+    pip install --require-virtualenv --upgrade sdepack # (1)!
+    ```
+
+    1. You may need to use `pip3` instead of `pip` depending on your Python installation.
+
+    !!! note
+        Command to activate the virtual env depends on your platform and shell. [More info](https://docs.python.org/3/library/venv.html#how-venvs-work)
 
-## Package managers
+### pipenv
+
+    pipenv install sdepack
 
 ### uv
 
-```bash
-# Add to a uv project
-uv add sdepack
+=== "Adding to uv project"
 
-# Or install into the current environment
-uv pip install sdepack
-```
+    ```bash
+    uv add sdepack
+    uv sync
+    ```
 
-### pipenv
+=== "Installing to uv environment"
 
-```bash
-pipenv install sdepack
-```
+    ```bash
+    uv venv
+    uv pip install sdepack
+    ```
 
 ### poetry
 
@@ -75,31 +83,59 @@ pdm add sdepack
 hatch add sdepack
 ```
 
-## Installing from source (GitHub)
+## [conda-forge](https://anaconda.org/conda-forge/sdepack)
+
+You can update your environment spec file by adding the following snippet.
+
+```yaml title="environment.yml"
+channels:
+  - conda-forge
+dependencies:
+  - pip
+  - pip:
+      - sdepack # (1)!
+```
+
+1. Specifying a version is recommended
+
+Installation can be done using the updated environment spec file.
+
+=== "conda"
+
+    ```bash
+    conda env update --file environment.yml
+    ```
+
+=== "micromamba"
+
+    ```bash
+    micromamba env update --file environment.yml
+    ```
+
+!!! note
+    Replace `environment.yml` with your actual environment spec file name if it's different.
+
+## [git](https://github.com/eggzec/sdepack)
 
 Install the latest development version directly from the repository:
 
 ```bash
 pip install --upgrade "git+https://github.com/eggzec/sdepack.git#egg=sdepack"
 ```
 
-### Building locally
+### Building from source
 
-Clone and build from source if you want to modify the Fortran code or test
-local changes:
+Clone and build from source if you want to modify the Fortran code or test local changes:
 
 ```bash
 git clone https://github.com/eggzec/sdepack.git
 cd sdepack
 pip install -e .
 ```
 
-This invokes the `meson` build system to compile the Fortran sources via
-`f2py` and install the resulting extension module in development mode.
-
 !!! warning "Fortran compiler required"
-    Source builds require a working Fortran compiler. On most Linux
-    distributions install `gfortran`:
+    Source builds require a working Fortran compiler (`gfortran` recommended) as well as
+    `meson` and `meson-python`.
 
 ```bash
 # Debian/Ubuntu
@@ -129,8 +165,5 @@ print("sdepack is working! Trajectory:", x)
 
 ## Dependencies
 
-| Package | Purpose |
-|---|---|
-| `numpy` | Array handling, `f2py` integration |
-
-No other runtime dependencies are required.
+- Python >= 3.10
+- [numpy](https://pypi.org/project/numpy)

mkdocs.yml

@@ -17,15 +17,21 @@ theme:
     - content.code.copy
 
 markdown_extensions:
-  - admonition
+  - attr_list
+  - md_in_html
   - tables
-  - fenced_code
+  - toc:
+      permalink: true
+      title: Page contents
+  - admonition
+  - pymdownx.details
   - pymdownx.superfences
-  - pymdownx.highlight
+  - pymdownx.highlight:
+      pygments_lang_class: true
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.arithmatex:
       generic: true
-  - toc:
-      permalink: true
 
 extra_javascript:
   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js