Skip to content

Commit a34f508

Browse files
GeorgePearseGeorgePearse
authored
Merge pull request #511 from BinItAI/feature/mkdocs-documentation
Implement MkDocs style documentation for visdet
2 parents cb4b744 + b0939dd commit a34f508

2 files changed

Lines changed: 193 additions & 0 deletions

File tree

‎DOCS_README.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Documentation Setup
2+
3+
This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) for documentation.
4+
5+
## Local Development
6+
7+
### Prerequisites
8+
9+
Install the documentation dependencies:
10+
11+
```bash
12+
uv pip install mkdocs mkdocs-material mkdocstrings[python] mkdocs-git-revision-date-localized-plugin mkdocs-awesome-pages-plugin
13+
```
14+
15+
### Build Documentation
16+
17+
To build the documentation:
18+
19+
```bash
20+
mkdocs build
21+
```
22+
23+
This generates static HTML files in the `site/` directory.
24+
25+
### Serve Documentation Locally
26+
27+
To preview the documentation locally:
28+
29+
```bash
30+
mkdocs serve
31+
```
32+
33+
Then open http://127.0.0.1:8000 in your browser. The documentation will auto-reload when you make changes.
34+
35+
## Documentation Structure
36+
37+
```
38+
docs/
39+
├── index.md # Landing page
40+
├── getting-started/
41+
│ ├── installation.md # Installation instructions
42+
│ └── quick-start.md # Quick start guide
43+
├── user-guide/
44+
│ ├── training.md # Training models
45+
│ ├── inference.md # Running inference
46+
│ └── configuration.md # Configuration guide
47+
├── api-reference/
48+
│ └── index.md # Auto-generated API docs
49+
├── development/
50+
│ ├── contributing.md # Contributing guidelines
51+
│ └── architecture.md # Architecture overview
52+
└── assets/
53+
└── images/ # Documentation images
54+
```
55+
56+
## Writing Documentation
57+
58+
### Markdown Basics
59+
60+
MkDocs uses standard Markdown with some extensions. See the [Material theme documentation](https://squidfunk.github.io/mkdocs-material/reference/) for available features.
61+
62+
### Code Blocks
63+
64+
Use fenced code blocks with syntax highlighting:
65+
66+
\`\`\`python
67+
from visdet import Detector
68+
69+
detector = Detector(config='config.py')
70+
\`\`\`
71+
72+
### Admonitions
73+
74+
Create callout boxes:
75+
76+
\`\`\`markdown
77+
!!! note
78+
This is a note.
79+
80+
!!! warning
81+
This is a warning.
82+
\`\`\`
83+
84+
### API Documentation
85+
86+
Use mkdocstrings to include API documentation:
87+
88+
\`\`\`markdown
89+
::: visdet.core.Detector
90+
options:
91+
show_source: true
92+
\`\`\`
93+
94+
## Deployment
95+
96+
Documentation is automatically deployed to GitHub Pages via GitHub Actions when changes are pushed to the `master` branch.
97+
98+
The workflow is defined in `.github/workflows/docs.yml`.

‎mkdocs.yml‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
site_name: visdet Documentation
2+
site_description: Object detection toolkit based on MMDetection
3+
site_author: visdet Contributors
4+
site_url: https://binitai.github.io/visdet/
5+
6+
repo_name: BinItAI/visdet
7+
repo_url: https://github.com/BinItAI/visdet
8+
edit_uri: edit/master/docs/
9+
10+
theme:
11+
name: material
12+
palette:
13+
# Palette toggle for light mode
14+
- media: "(prefers-color-scheme: light)"
15+
scheme: default
16+
primary: indigo
17+
accent: indigo
18+
toggle:
19+
icon: material/brightness-7
20+
name: Switch to dark mode
21+
# Palette toggle for dark mode
22+
- media: "(prefers-color-scheme: dark)"
23+
scheme: slate
24+
primary: indigo
25+
accent: indigo
26+
toggle:
27+
icon: material/brightness-4
28+
name: Switch to light mode
29+
features:
30+
- navigation.tabs
31+
- navigation.sections
32+
- navigation.top
33+
- navigation.tracking
34+
- search.suggest
35+
- search.highlight
36+
- content.tabs.link
37+
- content.code.annotation
38+
- content.code.copy
39+
language: en
40+
icon:
41+
repo: fontawesome/brands/github
42+
43+
plugins:
44+
- search
45+
- mkdocstrings:
46+
handlers:
47+
python:
48+
options:
49+
docstring_style: google
50+
show_source: true
51+
show_root_heading: true
52+
show_root_full_path: false
53+
members_order: source
54+
- git-revision-date-localized:
55+
enable_creation_date: true
56+
type: timeago
57+
58+
markdown_extensions:
59+
- pymdownx.highlight:
60+
anchor_linenums: true
61+
- pymdownx.inlinehilite
62+
- pymdownx.snippets
63+
- admonition
64+
- pymdownx.arithmatex:
65+
generic: true
66+
- footnotes
67+
- pymdownx.details
68+
- pymdownx.superfences
69+
- pymdownx.mark
70+
- attr_list
71+
- pymdownx.emoji:
72+
emoji_index: !!python/name:material.extensions.emoji.twemoji
73+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
74+
75+
nav:
76+
- Home: index.md
77+
- Getting Started:
78+
- Installation: getting-started/installation.md
79+
- Quick Start: getting-started/quick-start.md
80+
- User Guide:
81+
- Training: user-guide/training.md
82+
- Inference: user-guide/inference.md
83+
- Configuration: user-guide/configuration.md
84+
- API Reference:
85+
- Overview: api-reference/index.md
86+
- Development:
87+
- Contributing: development/contributing.md
88+
- Architecture: development/architecture.md
89+
90+
extra:
91+
social:
92+
- icon: fontawesome/brands/github
93+
link: https://github.com/BinItAI/visdet
94+
version:
95+
provider: mike

0 commit comments

Comments
 (0)