Use mkdocs for documentation

Author: chrisburr

.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true

.gitignore

@@ -91,3 +91,8 @@ docs/source/_build
 # CMT junk
 /*/*/x86_64-*-*-*/
 */*/cmt/Makefile
+
+# pixi environments
+.pixi
+pixi.lock
+*.egg-info

.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+        args: ["--unsafe"]
       - id: check-added-large-files
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
@@ -50,5 +51,7 @@ repos:
     rev: v2.4.1
     hooks:
     - id: codespell
-      args: ["--skip=diracx-client/src/diracx/client/_generated/*, diracx-[a-z]*/tests/*, diracx-testing/*, build/*, extensions/gubbins/gubbins-client/src/gubbins/client/_generated/*, extensions/gubbins/gubbins-*/tests/*",
-      "--ignore-words-list=CheckIn", "-w"]
+      args:
+        - "--skip=diracx-client/src/diracx/client/_generated/*, diracx-[a-z]*/tests/*, diracx-testing/*, build/*, extensions/gubbins/gubbins-client/src/gubbins/client/_generated/*, extensions/gubbins/gubbins-*/tests/*"
+        - "--ignore-words-list=CheckIn"
+        - "-w"

.readthedocs.yaml

@@ -0,0 +1,16 @@
+ version: 2
+
+ build:
+   os: "ubuntu-24.04"
+   tools:
+     python: "3"
+   # We recommend using a requirements file for reproducible builds.
+   # This is just a quick example to get started.
+   # https://docs.readthedocs.io/page/guides/reproducible-builds.html
+   jobs:
+     pre_install:
+       - pip install mkdocs-material
+       - pip install mkdocs-diracx-plugin@git+https://github.com/aldbr/mkdocs-diracx-plugin
+
+ mkdocs:
+   configuration: mkdocs.yml

docs/CLIENT.md

@@ -1,34 +1,3 @@
-## Run a full diracx demo
-
-This will allow you to run a demo setup.
-
-The code changes will be reflected in the demo.
-
-Requirement: docker, internet
-
-```bash
-# Clone the diracx repository
-git clone git@github.com:DIRACGrid/diracx.git
-
-# Clone the diracx-chart repository
-git clone git@github.com:DIRACGrid/diracx-charts.git
-
-# Run the demo
-diracx-charts/run_demo.sh diracx/
-```
-
-To login, click the **authorize** button
-
-![authorize](login_demo_1.png)
-
-Connect using the authorization code flow, ticking the "vo:diracAdmin" scope
-
-![codeflow](login_demo_2.png)
-
-And enter the credentials prompted by the `run_demo.sh` script in the `Dex` interface
-
-![Dexlogin](login_demo_3.png)
-
 ## Create the dev environment
 
 This will help you setup a dev environment to run the unit tests

docs/MIGRATION.md

@@ -1,6 +1,5 @@
 # Configuration
 
-This page describes the way by which configuration is handled within DiracX.
 Configuration refers to the central store of configuration data which is made available to both servers and clients.
 This is in contrast to "Settings" which are only available on the server side.
 Confidential information (such as passwords) is only handled in Settings, see the DiracX helm chart for details.
@@ -29,43 +28,5 @@ Currently the canonical source of configuration is from the legacy DIRAC Configu
 We foresee this will continue to be the case until the migration from DIRAC -> DiracX is complete.
 During this time, the DiracX configuration is not intended to be edited directly.
 The DiracX `default.yml` file differs in structure and contents from the legacy DIRAC Configuration Service.
-The legacy DIRAC CFG file can be converted into the new YAML format with:
 
-```bash
-DIRAC_COMPAT_ENABLE_CS_CONVERSION=true dirac internal legacy cs-sync dirac-cs.cfg diracx-config/default.yml
-```
-
-The following can be run on any client with a proxy
-
-```python
-#!/usr/bin/env python
-import subprocess
-import os
-import tempfile
-import zlib
-from pathlib import Path
-
-import DIRAC
-
-DIRAC.initialize()
-from DIRAC import gConfig
-from DIRAC.Core.Utilities.ReturnValues import returnValueOrRaise
-from DIRAC.ConfigurationSystem.Client.ConfigurationClient import ConfigurationClient
-
-client = ConfigurationClient(
-    url=gConfig.getValue("/DIRAC/Configuration/MasterServer", "")
-)
-data = returnValueOrRaise(client.getCompressedData())
-data = zlib.decompress(data)
-with tempfile.NamedTemporaryFile() as tmp:
-    tmp.write(data)
-    tmp.flush()
-    cmd = ["dirac", "internal", "legacy", "cs-sync", tmp.name, "default.yml"]
-    subprocess.run(
-        cmd, env=os.environ | {"DIRAC_COMPAT_ENABLE_CS_CONVERSION": "yes"}, check=True
-    )
-
-print("Synced CS to default.yml, now you can review the changes and commit/push them")
-```
-
-TODO: Document how we will actually do the sync for production deployments...
+See [how-to](../how-to/convert_cs.md) for how to convert.