docs: 📝 Introduce mkdocs-material to sahi project to have documentation page by onuralpszr · Pull Request #1210 · obss/sahi

onuralpszr · 2025-07-21T15:49:14Z

Introducing mkdocs-material to project and significant updates to the SAHI documentation and workflow configuration. It includes enhancements to the documentation structure, content, and presentation, as well as modifications to the workflow for dependency installation. Below is a summary of the most important changes grouped by theme:

Documentation Enhancements:

New Documentation Pages:

Added new documentation files for various SAHI components, such as annotation.md, auto_model.md, models/base.md, models/detectron2.md, models/huggingface.md, models/mmdet.md, models/roboflow.md, models/rtdetr.md, models/torchvision.md, models/ultralytics.md, models/yolov5.md, postprocess/combine.md, postprocess/utils.md, prediction.md, slicing.md, utils/coco.md, and utils/cv.md. Each file includes a reference to the respective module using the mkdocstrings syntax. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17]

Documentation Restructuring:

Renamed docs/README.md to docs/index.md and updated its content to include a visually appealing introduction to SAHI, complete with badges, links, and a teaser image. The file now serves as the homepage for the documentation. [1] [2] [3] [4]

Configuration for MkDocs:

Added a mkdocs.yml configuration file to enable the use of MkDocs for generating SAHI documentation. This includes setting up navigation, themes, plugins, and markdown extensions to enhance the documentation's usability and appearance.

Workflow Configuration Updates:

Modified the dependency installation step in .github/workflows/mmdet.yml to use uv sync --group dev --extra mmdet instead of uv sync --extra dev --extra mmdet. This change ensures better grouping of dependencies during installation.

Adds netlify.toml for Netlify deployment configuration for test in PR.

These updates collectively improve the documentation's structure, accessibility, and functionality while refining the workflow setup for better compatibility.

….toml

…et workflow

… documentation

onuralpszr · 2025-07-21T15:51:34Z

cc @fcakyon it is not completely done yet. But I wanted to post first initial PR so we can discuss further in PR to make it perfect. I had to some small adjustment in toml file for version and "override" package for pillow because mkdocs-material imaging and "inference" from roboflow have both different version choice so I am using small override to pass it. It won't effect page itself because I also moved all of them OUT of pypi extras, they won't be visible to anyone who installs from pypi (new pep standard landed a while ago so I wanted to get advantage of it.)

fcakyon · 2025-07-21T16:20:13Z

@onuralpszr thanks for this awesome PR 🎉

I have pushed 2 updates, now all tests pass, all your suggestions make sense 💯

Is a free Netlify account enough for our case?

onuralpszr · 2025-07-21T16:35:15Z

@onuralpszr thanks for this awesome PR 🎉

I have pushed 2 updates, now all tests pass, all your suggestions make sense 💯

Is a free Netlify account enough for our case?

I am actually testing netlify config at my own PR to see and show you a preview of docs. Netlify has limits for how much usage but based on PR and commit of this repo it is %99 fine, I don't think you will broke the limit for a while (300 min build time is limit, I used on new project a bit much did not break it.)

…s dependencies

onuralpszr · 2025-07-21T16:48:57Z

@fcakyon I made preview PR for myself to track docs and also here is preview link for to see docs preview :) Enjoy

https://docs-hello-mkdocs--obss-sahi-test-docs.netlify.app/
onuralpszr#1

fcakyon · 2025-07-21T16:50:40Z

@fcakyon I made preview PR for myself to track docs and also here is preview link for to see docs preview :) Enjoy

docs-hello-mkdocs--obss-sahi-test-docs.netlify.app onuralpszr#1

very fast and responsive! even the notebooks look great 🔥

onuralpszr · 2025-07-21T16:52:24Z

@fcakyon I made preview PR for myself to track docs and also here is preview link for to see docs preview :) Enjoy
docs-hello-mkdocs--obss-sahi-test-docs.netlify.app onuralpszr#1

very fast and responsive! even the notebooks look great 🔥

Main deployment will be in github pages If you okay with it. One big question do you have "custom domain" or do you want to use what github gave us ? (That will be URL ıf I am not wrong https://obss.github.io/sahi/ )

fcakyon · 2025-07-21T17:22:36Z

@onuralpszr we should remove notebooks from the demo folder to prevent duplication and update any reference to notebooks to the docs/notebooks folder.

fcakyon · 2025-07-21T17:23:09Z

@onuralpszr we should remove notebooks from the demo folder to prevent duplication and update any reference to notebooks to the docs/notebooks folder.

GitHub pages default URL is definitely fine, no need for a custom domain 👍🏻

onuralpszr · 2025-07-21T17:24:02Z

@onuralpszr we should remove notebooks from the demo folder to prevent duplication and update any reference to notebooks to the docs/notebooks folder.

Okay I was going to ask for it. I will also?update all of the url around readme as well

fcakyon · 2025-07-21T18:03:58Z

For future reference, please note that production documentation will be hosted on GitHub Pages. Additionally, PR documents will be deployed to Netlify for easier previewing. Can you confirm this, @onuralpszr?

onuralpszr · 2025-07-21T18:08:30Z

For future reference, please note that production documentation will be hosted on GitHub Pages. Additionally, PR documents will be deployed to Netlify for easier previewing. Can you confirm this, @onuralpszr?

Yes I can confirm 👍

…documentation path

fcakyon · 2025-07-24T12:20:39Z

@fcakyon, I’ve completed most of the work before the merge. I’ll also add a GitHub Page deployment action.

I have one question: would you prefer versioned documentation, such as ‘develop’ / ‘stable,’ or would you like to stick with a single version for now? It also depends on how you’d like to update the documentation it will naturally be more up-to-date than the ‘stable’ version If you keep single version. Typos and minor inconsistencies are acceptable, but breaking ABI changes would need to be handled differently.

Side note: I also noticed some mypy/class issues that I didn't want to address in this PR, but I’ll send a newer version in the next iteration.

@onuralpszr How about having a single version as you mentioned? We can have a dedicated md page giving details about breaking changes across versions.

onuralpszr · 2025-07-24T12:34:31Z

@fcakyon, I’ve completed most of the work before the merge. I’ll also add a GitHub Page deployment action.
I have one question: would you prefer versioned documentation, such as ‘develop’ / ‘stable,’ or would you like to stick with a single version for now? It also depends on how you’d like to update the documentation it will naturally be more up-to-date than the ‘stable’ version If you keep single version. Typos and minor inconsistencies are acceptable, but breaking ABI changes would need to be handled differently.
Side note: I also noticed some mypy/class issues that I didn't want to address in this PR, but I’ll send a newer version in the next iteration.

@onuralpszr How about having a single version as you mentioned? We can have a dedicated md page giving details about breaking changes across versions.

Okay I will be focusing on single version and I will add "CHANGELOG.md" so we can populate in time as well.

Thank you.

fcakyon · 2025-07-24T13:32:54Z

@onuralpszr netlify app is also configured for the repo 🚀

…tation Signed-off-by: Onuralp SEZER <thunderbirdtr@gmail.com>