Jev Kuznetsov
52 lines
1.3 KiB
Markdown
52 lines
1.3 KiB
Markdown
# Documentation
|
|
|
|
Make it easy to understand, run, and contribute to your project — for future you and for teammates.
|
|
|
|
## Tools by Language
|
|
|
|
| Language | Recommended | Alternatives |
|
|
|---|---|---|
|
|
| Python | `mkdocs` + Material | sphinx, pdoc |
|
|
| JavaScript/TS | VitePress | Docusaurus, JSDoc |
|
|
| Go | `pkgsite`, `godoc` | (built-in tooling is strong) |
|
|
| C++ | Doxygen | sphinx, mkdocs |
|
|
|
|
## Python — MkDocs + Material
|
|
|
|
Fast setup, Markdown-based, deploys to GitHub Pages in one command.
|
|
|
|
```bash
|
|
uv add --dev mkdocs-material
|
|
mkdocs new .
|
|
mkdocs serve # live preview at localhost:8000
|
|
mkdocs build # generate static site
|
|
mkdocs gh-deploy # push to GitHub Pages
|
|
```
|
|
|
|
`mkdocs.yml`:
|
|
|
|
```yaml
|
|
site_name: My Project
|
|
theme:
|
|
name: material
|
|
nav:
|
|
- Home: index.md
|
|
- API Reference: api.md
|
|
```
|
|
|
|
## What to Document
|
|
|
|
Minimum viable docs for any project:
|
|
|
|
1. **What it does** — one paragraph
|
|
2. **How to install** — exact commands, no assumptions
|
|
3. **How to run** — quickstart example
|
|
4. **How to develop** — how to run tests, linting, CI locally
|
|
|
|
## Tips
|
|
|
|
- Docs live in the repo — version them alongside the code
|
|
- A README is documentation; don't skip it even for internal projects
|
|
- Generate API docs from docstrings (`pdoc`, `pkgsite`) rather than writing them twice
|
|
- Often skipped, always regretted — write docs when the code is fresh
|