Skip to content

Mkdocs - #74

Merged
chenkasirer merged 10 commits into
mainfrom
mkdocs
Dec 11, 2025
Merged

chenkasirer merged 10 commits into
mainfrom
mkdocs

Conversation

@chenkasirer

@chenkasirer chenkasirer commented Dec 8, 2025 •

Copy link
Copy Markdown
Member

Migrated the documentation to mkdocs material from sphinx

@zeitunik ;)

image

What type of change is this?

  • Bug fix in a backwards-compatible manner.
  • New feature in a backwards-compatible manner.
  • Breaking change: bug fix or new feature that involve incompatible API changes.
  • Other (e.g. doc update, configuration, etc)

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

  • I added a line to the CHANGELOG.md file in the Unreleased section under the most fitting heading (e.g. Added, Changed, Removed).
  • I ran all tests on my computer and it's all green (i.e. invoke test).
  • I ran lint on my computer and there are no errors (i.e. invoke lint).
  • I added new functions/classes and made them available on a second-level import, e.g. compas.datastructures.Mesh.
  • I have added tests that prove my fix is effective or that my feature works.
  • I have added necessary documentation (if appropriate)

Copilot AI review requested due to automatic review settings December 8, 2025 17:56

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR migrates the documentation system from Sphinx to MkDocs Material, modernizing the documentation infrastructure and converting all documentation files from reStructuredText (RST) to Markdown format.

Key Changes:

  • Replaces Sphinx documentation system with MkDocs Material
  • Converts all RST documentation files to Markdown format
  • Updates documentation generation to output protobuf definitions as Markdown instead of HTML
  • Restructures GitHub Actions workflow for MkDocs-based deployment

Reviewed changes

Copilot reviewed 30 out of 33 changed files in this pull request and generated 8 comments.

Show a summary per file
File Description
src/compas_pb/invocations.py Modified docs task to generate markdown protobuf docs and build with mkdocs instead of Sphinx
pyproject.toml Added new [docs] optional dependency group with MkDocs packages; moved dependencies from dynamic loading to inline declarations
requirements-dev.txt Added mkdocs, mkdocs-material, and mkdocstrings dependencies (creates duplication with pyproject.toml)
mkdocs.yml New MkDocs configuration file with Material theme, plugins, and navigation structure
.github/workflows/docs.yml Replaced compas-actions.docs workflow with custom mkdocs deployment steps
docs/*.md New Markdown documentation files replacing RST versions (index, installation, examples, introduction, license, missing_compas_type)
docs/*.rst Old RST documentation files being removed
docs/reference/*.md New API reference pages using mkdocstrings for auto-documentation
docs/protobuf.md Auto-generated protobuf documentation in Markdown format (1295 lines)
docs/assets/images/* Logo images (SVG and PNG) for the documentation site

Comment thread src/compas_pb/invocations.py Outdated
docs(ctx, doctest, rebuild, check_links)
dist_dir = Path(ctx.base_folder) / "dist"

ctx.run(f"mkdocs build -c -d {dist_dir} -t material")

Copilot AI Dec 8, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The -t material flag is invalid for mkdocs build. The theme is already specified in mkdocs.yml (line 15: name: material). The -t flag doesn't exist in mkdocs CLI.

Remove the -t material flag from the command:

ctx.run(f"mkdocs build -c -d {dist_dir}")

Copilot uses AI. Check for mistakes.
Comment thread .github/workflows/docs.yml Outdated

- name: Install dependencies
run: |
pip install -e .[dev]

Copilot AI Dec 8, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The GitHub Actions workflow installs dependencies with pip install -e .[dev] but MkDocs dependencies are in the separate [docs] optional dependency group (defined in pyproject.toml lines 52-68). This will cause the workflow to fail because mkdocs and related packages won't be installed.

Change the installation command to include the docs dependencies:

pip install -e .[dev,docs]
Suggested change
pip install -e .[dev]
pip install -e .[dev,docs]

Copilot uses AI. Check for mistakes.
Comment thread requirements-dev.txt Outdated
Comment on lines +12 to +14
mkdocs
mkdocs-material
mkdocstrings[python]

Copilot AI Dec 8, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The requirements-dev.txt file now contains MkDocs-related dependencies (lines 12-14), but these have also been added to the [project.optional-dependencies.docs] section in pyproject.toml. Since pyproject.toml no longer dynamically loads from requirements-dev.txt (the dynamic loading was removed in lines 89-90), this creates duplication and potential version conflicts.

Consider either:

  1. Remove mkdocs dependencies from requirements-dev.txt since they're already in pyproject.toml under [docs]
  2. Or add them to the [dev] section in pyproject.toml if they should be part of dev dependencies

The typical pattern is to have documentation dependencies separate from development dependencies.

Copilot uses AI. Check for mistakes.
Comment thread mkdocs.yml
text: Roboto
code: Roboto Mono
logo: assets/images/compas_pb.png
favicon: public/favicon.ico

Copilot AI Dec 8, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The favicon path references public/favicon.ico but this file/directory doesn't exist in the repository. This will cause a 404 error when the documentation site tries to load the favicon.

Either:

  1. Create a docs/public/favicon.ico file
  2. Remove the favicon line if not needed
  3. Or use an existing image file like docs/assets/images/compas_pb.png

Example fix:

favicon: assets/images/compas_pb.png
Suggested change
favicon: public/favicon.ico
favicon: assets/images/compas_pb.png

Copilot uses AI. Check for mistakes.
Comment thread pyproject.toml
"compas_invocations2",
"invoke >=0.14",
"ruff",
"sphinx_compas2_theme",

Copilot AI Dec 8, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sphinx_compas2_theme package is still listed in the [dev] dependencies but it's only used for Sphinx documentation. Since the project has migrated to MkDocs, this dependency is no longer needed and should be removed to avoid installing unnecessary packages.

Copilot uses AI. Check for mistakes.
Comment thread mkdocs.yml
Comment on lines +11 to +12
version:
provider: mike

Copilot AI Dec 8, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The mkdocs.yml configures mike as the version provider (lines 11-12), but the GitHub Actions workflow uses mkdocs gh-deploy instead of mike deploy. This creates an inconsistency - either the workflow should use mike for versioned deployments, or the mike configuration should be removed from mkdocs.yml.

If versioning is desired, the workflow should use:

- name: Deploy to GitHub Pages
  run: |
    mike deploy --push --update-aliases $VERSION latest

If versioning is not needed, remove the version provider configuration from mkdocs.yml.

Suggested change
version:
provider: mike

Copilot uses AI. Check for mistakes.
Comment thread src/compas_pb/invocations.py Outdated
Comment on lines 193 to 194
# intercepting the `invoke docs` call so that the protobuf docs are generated first
# the single html file is linked to from the main docs site

Copilot AI Dec 8, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comment mentions "the single html file" but the output is now a Markdown file (protobuf.md), not an HTML file. Update the comment to reflect the actual output format:

# the markdown file is linked to from the main docs site

Copilot uses AI. Check for mistakes.
@gonzalocasas

Copy link
Copy Markdown
Member

Why that color? I thought that purple-ish was just a default color for testing it, but we would change it to the COMPAS blue before we go live on any of these themes

Comment thread mkdocs.yml Outdated
Comment on lines +14 to +19
theme:
name: material
palette:
scheme: slate
primary: indigo
accent: indigo

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@chenkasirer
chenkasirer merged commit c974212 into main Dec 11, 2025
17 checks passed
@chenkasirer
chenkasirer deleted the mkdocs branch December 11, 2025 10:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants