Skip to content

Commit 5b293fc

Browse files
micedremeilame-tayebjee
micedre
authored and
meilame-tayebjee
committed
docs: Add comprehensive documentation website
 - Sphinx setup with pydata-sphinx-theme - Complete API reference auto-generated from docstrings - Architecture documentation with diagrams - Getting started guide and tutorials
1 parent 723abe8 commit 5b293fc

33 files changed

+6497
-66
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- docs-website
8+
pull_request:
9+
branches:
10+
- main
11+
workflow_dispatch:
12+
13+
# Sets permissions for GitHub Pages deployment
14+
permissions:
15+
contents: read
16+
pages: write
17+
id-token: write
18+
19+
# Allow one concurrent deployment
20+
concurrency:
21+
group: "pages"
22+
cancel-in-progress: true
23+
24+
jobs:
25+
build:
26+
runs-on: ubuntu-latest
27+
28+
steps:
29+
- name: Checkout repository
30+
uses: actions/checkout@v4
31+
32+
- name: Set up Python
33+
uses: actions/setup-python@v5
34+
with:
35+
python-version: '3.11'
36+
37+
- name: Install uv
38+
uses: astral-sh/setup-uv@v4
39+
40+
- name: Install dependencies
41+
run: |
42+
uv sync --group docs
43+
44+
- name: Install Pandoc (required for nbsphinx)
45+
run: |
46+
sudo apt-get update
47+
sudo apt-get install -y pandoc
48+
49+
- name: Build documentation
50+
run: |
51+
uv run sphinx-build -b html docs/source build/html
52+
53+
- name: Upload artifact
54+
uses: actions/upload-pages-artifact@v3
55+
with:
56+
path: build/html
57+
58+
deploy:
59+
needs: build
60+
if: github.event_name == 'push' && ( github.ref == 'refs/heads/main' || github.ref == 'refs/heads/docs-website' )
61+
runs-on: ubuntu-latest
62+
63+
environment:
64+
name: github-pages
65+
url: ${{ steps.deployment.outputs.page_url }}
66+
67+
steps:
68+
- name: Deploy to GitHub Pages
69+
id: deployment
70+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,8 @@ instance/
7070

7171
# Sphinx documentation
7272
docs/_build/
73+
docs/build/
74+
docs/source/_autosummary/
7375

7476
# PyBuilder
7577
.pybuilder/
@@ -165,8 +167,7 @@ lightning_logs/
165167
# Training data
166168
data/training_data.txt
167169

168-
# Docs
169-
docs/
170+
# Other
170171
fastTextAttention.py
171172
*.pth
172173

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# torchTextClassifiers
22

3+
[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://inseeflab.github.io/torchTextClassifiers/)
4+
35
A unified, extensible framework for text classification with categorical variables built on [PyTorch](https://pytorch.org/) and [PyTorch Lightning](https://lightning.ai/docs/pytorch/stable/).
46

57
## 🚀 Features
@@ -30,6 +32,16 @@ uv sync
3032
pip install -e .
3133
```
3234

35+
## 📖 Documentation
36+
37+
Full documentation is available at: **https://inseeflab.github.io/torchTextClassifiers/**
38+
39+
The documentation includes:
40+
- **Getting Started**: Installation and quick start guide
41+
- **Architecture**: Understanding the 3-layer design
42+
- **Tutorials**: Step-by-step guides for different use cases
43+
- **API Reference**: Complete API documentation
44+
3345
## 📝 Usage
3446

3547
Checkout the [notebook](notebooks/example.ipynb) for a quick start.

‎docs/Makefile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Minimal makefile for Sphinx documentation
2+
3+
# You can set these variables from the command line, and also
4+
# from the environment for the first two.
5+
SPHINXOPTS ?=
6+
SPHINXBUILD ?= sphinx-build
7+
SOURCEDIR = source
8+
BUILDDIR = build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/_static/custom.css‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
/* Custom styling for torchTextClassifiers documentation with pydata-sphinx-theme */
2+
3+
/* Improve code block styling */
4+
div.highlight {
5+
border-radius: 6px;
6+
border: 1px solid var(--pst-color-border);
7+
margin: 1em 0;
8+
}
9+
10+
div.highlight pre {
11+
padding: 12px;
12+
overflow-x: auto;
13+
}
14+
15+
/* Better admonition styling */
16+
.admonition {
17+
border-radius: 6px;
18+
padding: 1rem;
19+
margin: 1rem 0;
20+
}
21+
22+
.admonition-title {
23+
font-weight: 600;
24+
margin-bottom: 0.5rem;
25+
}
26+
27+
/* Improve table styling */
28+
table.docutils {
29+
border-collapse: collapse;
30+
width: 100%;
31+
margin: 1em 0;
32+
}
33+
34+
table.docutils td,
35+
table.docutils th {
36+
border: 1px solid var(--pst-color-border);
37+
padding: 0.5rem;
38+
}
39+
40+
table.docutils th {
41+
background-color: var(--pst-color-surface);
42+
font-weight: 600;
43+
}
44+
45+
/* Navigation improvements */
46+
.bd-sidebar {
47+
font-size: 0.9rem;
48+
}
49+
50+
.bd-sidebar .nav-link {
51+
padding: 0.25rem 0.5rem;
52+
}
53+
54+
/* Logo text styling */
55+
.navbar-brand {
56+
font-weight: 600;
57+
font-size: 1.25rem;
58+
}
59+
60+
/* Improve inline code styling */
61+
code.docutils.literal {
62+
background-color: var(--pst-color-surface);
63+
padding: 0.1em 0.4em;
64+
border-radius: 3px;
65+
font-size: 0.9em;
66+
}
67+
68+
/* Better spacing for content */
69+
.bd-content {
70+
padding: 2rem;
71+
}
72+
73+
/* Improve heading spacing */
74+
.bd-content h1 {
75+
margin-top: 0;
76+
margin-bottom: 1.5rem;
77+
padding-bottom: 0.5rem;
78+
border-bottom: 2px solid var(--pst-color-border);
79+
}
80+
81+
.bd-content h2 {
82+
margin-top: 2rem;
83+
margin-bottom: 1rem;
84+
}
85+
86+
.bd-content h3 {
87+
margin-top: 1.5rem;
88+
margin-bottom: 0.75rem;
89+
}
90+
91+
/* Cards and grids (from sphinx-design) */
92+
.sd-card {
93+
border-radius: 8px;
94+
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
95+
transition: box-shadow 0.3s ease;
96+
}
97+
98+
.sd-card:hover {
99+
box-shadow: 0 4px 8px rgba(0, 0, 0, 0.15);
100+
}
101+
102+
/* Improve footer spacing */
103+
footer.bd-footer {
104+
margin-top: 3rem;
105+
padding-top: 2rem;
106+
border-top: 1px solid var(--pst-color-border);
107+
}
108+
109+
/* Better responsive images */
110+
img {
111+
max-width: 100%;
112+
height: auto;
113+
border-radius: 4px;
114+
}
115+
116+
/* Improve API documentation layout */
117+
dl.py.class,
118+
dl.py.function,
119+
dl.py.method {
120+
margin-bottom: 2rem;
121+
}
122+
123+
dt.sig {
124+
background-color: var(--pst-color-surface);
125+
padding: 0.5rem 1rem;
126+
border-radius: 4px;
127+
border-left: 3px solid var(--pst-color-primary);
128+
}
129+
130+
dd {
131+
margin-left: 2rem;
132+
margin-top: 0.5rem;
133+
}
134+
135+
/* Parameter list styling */
136+
dl.field-list {
137+
margin-top: 1rem;
138+
}
139+
140+
dl.field-list dt {
141+
font-weight: 600;
142+
margin-bottom: 0.25rem;
143+
}
144+
145+
dl.field-list dd {
146+
margin-left: 1.5rem;
147+
margin-bottom: 0.5rem;
148+
}

‎docs/source/_static/logo-ttc-dark.svg‎

Lines changed: 16 additions & 0 deletions
Loading

‎docs/source/_static/logo-ttc-light.svg‎

Lines changed: 16 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)