Migrate docs to Zensical, expand dev docs

.github/workflows/docs.yml

@@ -1,27 +1,28 @@
-# https://squidfunk.github.io/mkdocs-material/publishing-your-site/?h=#with-github-actions
-name: Deploy Docs
+name: Documentation
 on:
   push:
     branches:
       - main
-
 permissions:
-  contents: write
-
+  contents: read
+  pages: write
+  id-token: write
 jobs:
   deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v4
+      - uses: actions/configure-pages@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v3
+      - run: pip install zensical
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v5
         with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-      - run: pip install mkdocs-material mkdocs-section-index
-      - run: mkdocs gh-deploy --force
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment

.pre-commit-config.yaml

@@ -8,6 +8,11 @@ repos:
     -   id: check-ast
     -   id: check-toml
     -   id: check-yaml
+        exclude: mkdocs.yml
+    -   id: check-yaml
+        name: check-yaml (mkdocs)
+        files: mkdocs.yml
+        args: ['--unsafe']
     -   id: check-added-large-files
     -   id: check-builtin-literals
 

docker/docs/Dockerfile

@@ -1,4 +1,3 @@
-FROM squidfunk/mkdocs-material
-RUN python -m pip install mkdocs-section-index
-ENTRYPOINT ["mkdocs"]
+FROM zensical/zensical
+ENTRYPOINT ["zensical"]
 CMD ["serve", "--dev-addr=0.0.0.0:8000"]

docker/python/Dockerfile

@@ -13,7 +13,7 @@ RUN python -m pip install uv
 WORKDIR /app
 COPY pyproject.toml .
 
-RUN uv pip install -e ".[dev]"
+RUN uv pip install -e ".[dev, tests]"
 COPY . /app
 
 RUN mkdir /config

docs/contributing/code_of_conduct.md

@@ -0,0 +1,97 @@
+# Contributor Covenant Code of Conduct
+
+This is a temporary Code of Conduct until OpenML establishes one for all
+repositories in its organisation.
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+Moreover, we expect participation to be human-driven.
+While AI may be used to aid in creating code contributions or to communicate more effectively,
+it is a poor substitute for human intelligence.
+Additionally, the ease with which such content is generated provides a significant burden on
+maintainers if applied without consideration (see also, [The Cost of AI in Open Source Maintenance](https://adrin.info/the-cost-of-ai-in-open-source-maintenance.html)
+).
+As a result, we expect you to understand the code contributions you submit and
+minimize the use of AI in dialogue.
+
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at `openmlhq@googlegroups.com`.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+Enforcement may take the shape of a correction, warning, or (temporary) ban at the discretion
+of the community leaders.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

docs/contributing/index.md

@@ -23,6 +23,13 @@ When you open a bug report, please include:
  - a description of the encountered behavior,
  - and any additional information that you think may be relevant, such as which environment you encountered it in, or when you first encountered the bug.
 
+### Documentation
+
+For minor fixes such as correcting a typo or a broken link, it's fine to make the changes and submit them through a pull request.
+For larger changes, please make sure you are assigned to an issue first as is described
+in the "[Code](#code)" section of this page. Then, visit the "[Developer Documentation](../development/documentation.md)"
+page to learn how to contribute documentation changes.
+
 ### Code
 
 If you want to make code contributions, please first make sure there is an open issue
@@ -33,14 +40,18 @@ everything is clear, it's not out of date, and "officially" assign you to the is
 that others know its being worked on. Making sure there is a clear description and clear
 assignment helps prevent a situation where someone makes a large contribution that is
 unwanted, or is simultaneously developed by someone else. With an issue assigned,
-please head over to the "[Development](contributing.md)" section.
+please head over to the "[Setting up the development environment](../development/setup.md)" section.
 
-### Documentation
+!!! info "Help Wanted?"
+
+    We learned that working with community contributions during the development of
+    the first feature-complete release of the REST API is complicated.
+    While we are entirely grateful that so many people take an interest and want to help,
+    the majority of the work is figuring out what the desired behavior and interface of the
+    REST API should be. Making these decisions requires a lot of context about the OpenML platform,
+    ecosystem, and its history. For this reason, we restrict community code contributions in this
+    project to issues that are marked "Good First Issue" or "Help Wanted" for now.
 
-For minor fixes, it's fine to make the changes and submit them through a pull request.
-For larger changes, please make sure you are assigned to an issue first as is described
-in the "[Code](#code)" section of this page. Then, visit the "[Documentation](documentation.md)"
-page to learn how to contribute documentation changes.
 
 ### Other
 

docs/development/CI_CD.md

@@ -0,0 +1,17 @@
+We have the following GitHub actions:
+
+ - `.github/workflows/docker-publish.yml`: Build and publish a new Docker image to [our DockerHub repository](https://hub.docker.com/r/openml/rest-api) on release.
+ - `.github/workflows/docs.yml`: Build and deploy these documentation pages on a merge to the main branch.
+ - `.github/workflows/tests.yml`: Run all tests on pull requests and a push to main, pushes code coverage reports to Codecov.
+
+Additionally, we also have the following services configured:
+
+ - `.pre-commit-config.yaml`: For local pre-commits, but also used by pre-commit.ci on pull requests.
+ - `codecov.yaml`: For providing code coverage reports on pull requests.
+ - `CodeRabbit` and `Sourcery AI` for automated code reviews.
+
+ !!! example "On AI code reviews"
+
+    We are currently experimenting with AI code reviews.
+    For all their flaws in code generation, these bots do regularly point out typos and sometimes bring in context beyond the authors' familiarity.
+    They also make poor suggestions, but those are typically easy to identify and ignore.