docs: 📝 Introduce mkdocs-material to sahi project to have documentation page #1210
Conversation
|
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.) |
|
@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? |
f68ae33 to
ce46414
Compare
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.) |
ce46414 to
b35a1c1
Compare
b35a1c1 to
a6739a2
Compare
|
@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/ |
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/ ) |
|
@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 👍🏻 |
Okay I was going to ask for it. I will also?update all of the url around readme as well |
|
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 👍 |
@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. |
|
@onuralpszr netlify app is also configured for the repo 🚀 |
b3e078f to
4e01d3f
Compare
…tation Signed-off-by: Onuralp SEZER <[email protected]>
Signed-off-by: Onuralp SEZER <[email protected]>
4e01d3f to
5d7ec31
Compare
|
@fcakyon I include single version style for docs and I also added dependabot for "CI" I don't know your strategy yet about updating packages in pyproject.toml so I didn't not added yet. I only focused on docs and actions and CI first. |
|
@fcakyon after merge we also need to setup "gh-pages" as in settings->pages of repository enable "github packages and select "gh-pages" repo as documentation place and folder would be / (root) |
57bb99a to
d41d017
Compare
Signed-off-by: Onuralp SEZER <[email protected]>
|
@fcakyon changelog completely added. https://deploy-preview-1--obss-sahi-test-docs.netlify.app/changelog/ |
Signed-off-by: Onuralp SEZER <[email protected]>
…s and keep originals Signed-off-by: Onuralp SEZER <[email protected]>
efff9fa to
cd04c08
Compare
Signed-off-by: Onuralp SEZER <[email protected]>
…inks for docs Signed-off-by: Onuralp SEZER <[email protected]>
…eractive examples for utilities
…etailed examples for pip, conda, and git
Signed-off-by: Onuralp SEZER <[email protected]>
|
Better Quick Start Installation Status |
|
Index page also updated (main infos got from paper) https://deploy-preview-1--obss-sahi-test-docs.netlify.app/#what-is-sahi |
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:
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, andutils/cv.md. Each file includes a reference to the respective module using themkdocstringssyntax. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17]Documentation Restructuring:
docs/README.mdtodocs/index.mdand 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:
mkdocs.ymlconfiguration 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:
.github/workflows/mmdet.ymlto useuv sync --group dev --extra mmdetinstead ofuv 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.