Skip to content

Commit 83108b2

Browse files
micedremicedre
committed
First doc draft
1 parent 715f612 commit 83108b2

12 files changed

+3042
-0
lines changed

‎docs/README.md

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# torchTextClassifiers Documentation
2+
3+
This directory contains the documentation generation system for torchTextClassifiers.
4+
5+
## Quick Start
6+
7+
1. **Install dependencies:**
8+
```bash
9+
uv sync --group docs
10+
```
11+
12+
2. **Generate and serve documentation:**
13+
```bash
14+
uv run python generate_docs.py --all
15+
```
16+
17+
3. **Open your browser to http://localhost:8000**
18+
19+
## Commands
20+
21+
- `uv run python generate_docs.py --build` - Generate documentation
22+
- `uv run python generate_docs.py --serve` - Serve on localhost:8000
23+
- `uv run python generate_docs.py --all` - Build and serve
24+
- `uv run python generate_docs.py --clean` - Clean build directory
25+
- `uv run python generate_docs.py --serve --port 8080` - Custom port
26+
27+
## Features
28+
29+
✅ **Auto-generated API docs** from docstrings
30+
✅ **Beautiful HTML theme** with navigation
31+
✅ **Architecture diagrams** and examples
32+
✅ **Search functionality**
33+
✅ **Mobile-responsive design**
34+
✅ **Copy-to-clipboard** code examples
35+
✅ **Fast local development** server
36+
37+
## Documentation Structure
38+
39+
```
40+
docs/
41+
├── source/ # Sphinx source files
42+
│ ├── conf.py # Sphinx configuration
43+
│ ├── index.rst # Main documentation page
44+
│ ├── api.rst # Auto-generated API reference
45+
│ ├── examples.rst # Usage examples and tutorials
46+
│ ├── architecture.rst # Framework architecture
47+
│ └── installation.rst # Installation guide
48+
├── build/ # Generated documentation
49+
│ └── html/ # HTML output
50+
└── README.md # This file
51+
```
52+
53+
## Customization
54+
55+
The documentation system is highly customizable:
56+
57+
- **Themes:** Edit `source/conf.py` to change Sphinx theme
58+
- **Styling:** Modify `source/_static/custom.css` for custom CSS
59+
- **JavaScript:** Add features in `source/_static/custom.js`
60+
- **Content:** Edit `.rst` files in `source/` directory
61+
62+
## Dependencies
63+
64+
Documentation dependencies are managed through uv and defined in `pyproject.toml`:
65+
66+
```toml
67+
[dependency-groups]
68+
docs = [
69+
"sphinx>=5.0.0",
70+
"sphinx-rtd-theme>=1.2.0",
71+
"sphinx-autodoc-typehints>=1.19.0",
72+
"sphinxcontrib-napoleon>=0.7",
73+
"sphinx-copybutton>=0.5.0",
74+
"myst-parser>=0.18.0",
75+
"sphinx-design>=0.3.0"
76+
]
77+
```
78+
79+
## Development Workflow
80+
81+
1. **Make changes** to docstrings in source code
82+
2. **Rebuild docs** with `uv run python generate_docs.py --build`
83+
3. **Preview changes** with `uv run python generate_docs.py --serve`
84+
4. **Iterate** until satisfied
85+
86+
The documentation automatically extracts docstrings from the codebase, so keeping docstrings up-to-date will automatically improve the documentation.

‎docs/source/_static/custom.css

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
/* Custom CSS for torchTextClassifiers documentation */
2+
3+
/* Improve code block styling */
4+
.highlight {
5+
background-color: #f8f9fa;
6+
border: 1px solid #e9ecef;
7+
border-radius: 6px;
8+
padding: 1rem;
9+
margin: 1rem 0;
10+
}
11+
12+
/* Architecture diagrams */
13+
.architecture-diagram {
14+
font-family: monospace;
15+
background-color: #f6f8fa;
16+
padding: 1rem;
17+
border-radius: 6px;
18+
overflow-x: auto;
19+
white-space: pre;
20+
}
21+
22+
/* API reference styling */
23+
.api-reference .class {
24+
border-left: 4px solid #2980b9;
25+
padding-left: 1rem;
26+
margin: 1rem 0;
27+
}
28+
29+
/* Examples styling */
30+
.example-section {
31+
background-color: #f8f9fa;
32+
border: 1px solid #dee2e6;
33+
border-radius: 8px;
34+
padding: 1.5rem;
35+
margin: 2rem 0;
36+
}
37+
38+
/* Performance tips */
39+
.performance-tip {
40+
background-color: #e8f5e8;
41+
border-left: 4px solid #28a745;
42+
padding: 1rem;
43+
margin: 1rem 0;
44+
}
45+
46+
/* Warning boxes */
47+
.warning {
48+
background-color: #fff3cd;
49+
border-left: 4px solid #ffc107;
50+
padding: 1rem;
51+
margin: 1rem 0;
52+
}
53+
54+
/* Navigation improvements */
55+
.wy-nav-content {
56+
max-width: 1200px;
57+
}
58+
59+
/* Table styling */
60+
table {
61+
margin: 1rem 0;
62+
border-collapse: collapse;
63+
width: 100%;
64+
}
65+
66+
table th, table td {
67+
border: 1px solid #dee2e6;
68+
padding: 0.75rem;
69+
text-align: left;
70+
}
71+
72+
table th {
73+
background-color: #f8f9fa;
74+
font-weight: 600;
75+
}
76+
77+
/* Responsive improvements */
78+
@media (max-width: 768px) {
79+
.architecture-diagram {
80+
font-size: 0.8rem;
81+
}
82+
83+
.wy-nav-content {
84+
margin-left: 0;
85+
}
86+
}
87+
88+
/* Syntax highlighting improvements */
89+
.highlight .k { color: #0000ff; } /* Keywords */
90+
.highlight .s { color: #008000; } /* Strings */
91+
.highlight .c { color: #808080; } /* Comments */
92+
.highlight .n { color: #000000; } /* Names */
93+
94+
/* Footer styling */
95+
.footer {
96+
margin-top: 2rem;
97+
padding-top: 1rem;
98+
border-top: 1px solid #dee2e6;
99+
color: #6c757d;
100+
font-size: 0.9rem;
101+
}

‎docs/source/_static/custom.js

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
// Custom JavaScript for torchTextClassifiers documentation
2+
3+
document.addEventListener('DOMContentLoaded', function() {
4+
// Add copy buttons to code blocks
5+
addCopyButtons();
6+
7+
// Improve navigation
8+
improveNavigation();
9+
10+
// Add search enhancements
11+
enhanceSearch();
12+
});
13+
14+
function addCopyButtons() {
15+
const codeBlocks = document.querySelectorAll('pre');
16+
17+
codeBlocks.forEach(function(block) {
18+
const button = document.createElement('button');
19+
button.className = 'copy-button';
20+
button.textContent = 'Copy';
21+
button.style.cssText = `
22+
position: absolute;
23+
top: 8px;
24+
right: 8px;
25+
background: #007bff;
26+
color: white;
27+
border: none;
28+
border-radius: 4px;
29+
padding: 4px 8px;
30+
font-size: 12px;
31+
cursor: pointer;
32+
opacity: 0.7;
33+
transition: opacity 0.2s;
34+
`;
35+
36+
button.addEventListener('click', function() {
37+
const code = block.querySelector('code');
38+
const text = code ? code.textContent : block.textContent;
39+
40+
navigator.clipboard.writeText(text).then(function() {
41+
button.textContent = 'Copied!';
42+
setTimeout(function() {
43+
button.textContent = 'Copy';
44+
}, 2000);
45+
});
46+
});
47+
48+
button.addEventListener('mouseenter', function() {
49+
button.style.opacity = '1';
50+
});
51+
52+
button.addEventListener('mouseleave', function() {
53+
button.style.opacity = '0.7';
54+
});
55+
56+
block.style.position = 'relative';
57+
block.appendChild(button);
58+
});
59+
}
60+
61+
function improveNavigation() {
62+
// Add smooth scrolling to anchor links
63+
const anchorLinks = document.querySelectorAll('a[href^="#"]');
64+
65+
anchorLinks.forEach(function(link) {
66+
link.addEventListener('click', function(e) {
67+
e.preventDefault();
68+
const target = document.querySelector(this.getAttribute('href'));
69+
if (target) {
70+
target.scrollIntoView({
71+
behavior: 'smooth',
72+
block: 'start'
73+
});
74+
}
75+
});
76+
});
77+
78+
// Highlight current section in navigation
79+
highlightCurrentSection();
80+
}
81+
82+
function highlightCurrentSection() {
83+
const sections = document.querySelectorAll('h1, h2, h3');
84+
const navLinks = document.querySelectorAll('.wy-menu-vertical a');
85+
86+
function updateActiveLink() {
87+
let current = '';
88+
89+
sections.forEach(function(section) {
90+
const rect = section.getBoundingClientRect();
91+
if (rect.top <= 100) {
92+
current = section.id;
93+
}
94+
});
95+
96+
navLinks.forEach(function(link) {
97+
link.classList.remove('current');
98+
if (link.getAttribute('href') === '#' + current) {
99+
link.classList.add('current');
100+
}
101+
});
102+
}
103+
104+
window.addEventListener('scroll', updateActiveLink);
105+
updateActiveLink();
106+
}
107+
108+
function enhanceSearch() {
109+
// Add keyboard shortcuts for search
110+
document.addEventListener('keydown', function(e) {
111+
// Ctrl+K or Cmd+K to focus search
112+
if ((e.ctrlKey || e.metaKey) && e.key === 'k') {
113+
e.preventDefault();
114+
const searchInput = document.querySelector('input[name="q"]');
115+
if (searchInput) {
116+
searchInput.focus();
117+
}
118+
}
119+
120+
// Escape to clear search
121+
if (e.key === 'Escape') {
122+
const searchInput = document.querySelector('input[name="q"]');
123+
if (searchInput && searchInput === document.activeElement) {
124+
searchInput.value = '';
125+
searchInput.blur();
126+
}
127+
}
128+
});
129+
}
130+
131+
// Add version info to footer
132+
function addVersionInfo() {
133+
const footer = document.querySelector('.rst-footer-buttons');
134+
if (footer) {
135+
const versionInfo = document.createElement('div');
136+
versionInfo.innerHTML = `
137+
<div class="footer">
138+
Built with ❤️ by the torchTextClassifiers team |
139+
<a href="https://github.com/your-org/torch-fastText">View on GitHub</a>
140+
</div>
141+
`;
142+
footer.parentNode.insertBefore(versionInfo, footer.nextSibling);
143+
}
144+
}
145+
146+
// Initialize additional features
147+
document.addEventListener('DOMContentLoaded', function() {
148+
addVersionInfo();
149+
});

0 commit comments

Comments
 (0)