Skip to content

Commit c9256cc

Browse files
dimitri-yatsenkodimitri-yatsenko
committed
docs: implement Phase 1 versioning indicators
Add global version indicators to improve clarity for users on different DataJoint versions: **Global Indicators:** - Site-wide banner on every page showing 'DataJoint 2.0+' with migration link - Enhanced home page with prominent version warning admonition - Added 'Which Version Am I Using?' collapsible section on landing page **Feature-Level Support:** - Custom CSS for version admonitions (version-added, version-changed, version-deprecated) - Inline version badge styles for API reference - Code comparison styles for showing legacy vs current patterns **New Documentation:** - Added about/versioning.md explaining all version indicators - Added to About navigation section **Configuration:** - Enabled 'admonition' markdown extension for !!! blocks - Added extra.css for custom version styling This implements Phase 1 of the versioning strategy (see VERSIONING-STRATEGY.md). Phase 2-3 will add version annotations to specific features and API docs.
1 parent 6d7bf91 commit c9256cc

5 files changed

Lines changed: 280 additions & 3 deletions

File tree

‎mkdocs.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,7 @@ nav:
111111
- About:
112112
- about/index.md
113113
- History: about/history.md
114+
- Documentation Versioning: about/versioning.md
114115
- Platform: https://www.datajoint.com/sign-up
115116
- Citation: about/citation.md
116117
- Publications: about/publications.md
@@ -180,6 +181,7 @@ plugins:
180181
- images/*md
181182
- "*/SUMMARY.md"
182183
markdown_extensions:
184+
- admonition # Enable !!! admonition blocks
183185
- attr_list
184186
- md_in_html
185187
- toc:

‎src/.overrides/main.html‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
{% extends "base.html" %}
22

3+
{% block announce %}
4+
<div class="md-banner">
5+
<div class="md-banner__inner md-grid md-typeset">
6+
<p>
7+
📖 You are viewing documentation for <strong>DataJoint {{ config.extra.datajoint_version }}+</strong>
8+
·
9+
<a href="{{ config.site_url }}how-to/migrate-to-v20/">
10+
Migration guide for legacy users (pre-2.0)
11+
</a>
12+
</p>
13+
</div>
14+
</div>
15+
{% endblock %}
16+
317
{% block extrahead %}
418
<script
519
src="https://www.datadoghq-browser-agent.com/us1/v4/datadog-rum.js"

‎src/about/versioning.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Documentation Versioning
2+
3+
This page explains how version information is indicated throughout the DataJoint documentation.
4+
5+
## Documentation Scope
6+
7+
**This documentation covers DataJoint 2.0 and later.** All code examples and tutorials use DataJoint 2.0+ syntax and APIs.
8+
9+
If you're using legacy DataJoint (version 0.14.x or earlier), please visit the [legacy documentation](https://datajoint.github.io/datajoint-python) or follow the [Migration Guide](../how-to/migrate-to-v20.md) to upgrade.
10+
11+
## Version Indicators
12+
13+
### Global Indicators
14+
15+
**Site-wide banner:** Every page displays a banner indicating you're viewing documentation for DataJoint 2.0+, with a link to the migration guide for legacy users.
16+
17+
**Footer:** The footer shows which version of DataJoint this documentation covers.
18+
19+
### Feature-Level Indicators
20+
21+
For specific features, you'll see version admonitions:
22+
23+
#### New Features
24+
25+
!!! version-added "New in 2.0"
26+
27+
This indicates a feature that was introduced in DataJoint 2.0.
28+
29+
**Example from documentation:**
30+
31+
!!! version-added "New in 2.0"
32+
33+
Semantic matching validates joins based on lineage tracking. This feature was introduced in DataJoint 2.0.
34+
35+
#### Changed Behavior
36+
37+
!!! version-changed "Changed in 2.0"
38+
39+
This indicates behavior that changed from previous versions.
40+
41+
**Example from documentation:**
42+
43+
!!! version-changed "Changed in 2.0"
44+
45+
The fetch API was redesigned in 2.0. Use `to_dicts()` or `to_arrays()` instead of `fetch()`.
46+
47+
**Legacy (pre-2.0):** `data = table.fetch()`
48+
**Current (2.0+):** `data = table.to_dicts()`
49+
50+
#### Deprecated Features
51+
52+
!!! version-deprecated "Deprecated in 2.0, removed in 3.0"
53+
54+
This indicates features that are deprecated and will be removed in future versions.
55+
56+
**Example from documentation:**
57+
58+
!!! version-deprecated "Deprecated in 2.0, removed in 3.0"
59+
60+
The `external` storage type is deprecated. Use unified stores with `<blob@store>` syntax instead.
61+
62+
### Inline Version Badges
63+
64+
In API reference documentation, you may see inline version badges:
65+
66+
- `to_dicts()` <span class="version-badge">v2.0+</span> - Retrieve as list of dicts
67+
- `fetch()` <span class="version-badge deprecated">deprecated</span> - Legacy fetch API
68+
69+
## Checking Your Version
70+
71+
To check which version of DataJoint you're using:
72+
73+
```python
74+
import datajoint as dj
75+
print(dj.__version__)
76+
```
77+
78+
- **Version 2.0 or higher:** You're on the current version
79+
- **Version 0.14.x or lower:** You're on legacy DataJoint
80+
81+
## Migration Path
82+
83+
If you're upgrading from legacy DataJoint (pre-2.0):
84+
85+
1. **Review** the [What's New in 2.0](../explanation/whats-new-2.md) page to understand major changes
86+
2. **Follow** the [Migration Guide](../how-to/migrate-to-v20.md) for step-by-step upgrade instructions
87+
3. **Reference** this documentation for updated syntax and APIs
88+
89+
## Legacy Documentation
90+
91+
For DataJoint 0.x documentation, visit:
92+
93+
**[datajoint.github.io/datajoint-python](https://datajoint.github.io/datajoint-python)**
94+
95+
## Version History
96+
97+
| Version | Release Date | Major Changes |
98+
|---------|--------------|---------------|
99+
| 2.0 | 2026 | Redesigned fetch API, unified stores, per-table jobs, semantic matching |
100+
| 0.14.x | 2020-2025 | Legacy version with external storage |
101+
| 0.13.x | 2019 | Legacy version |
102+
103+
For complete version history, see the [changelog](https://github.com/datajoint/datajoint-python/releases).

‎src/assets/stylesheets/extra.css‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
/* ===================================================================
2+
DataJoint Documentation Custom Styles
3+
=================================================================== */
4+
5+
/* -------------------------------------------------------------------
6+
Version Banner (Site-wide)
7+
------------------------------------------------------------------- */
8+
9+
.md-banner {
10+
background-color: var(--md-primary-fg-color);
11+
color: var(--md-primary-bg-color);
12+
font-size: 0.7rem;
13+
padding: 0.4rem 0;
14+
text-align: center;
15+
}
16+
17+
.md-banner__inner {
18+
padding: 0;
19+
}
20+
21+
.md-banner p {
22+
margin: 0;
23+
padding: 0;
24+
}
25+
26+
.md-banner a {
27+
color: var(--md-primary-bg-color);
28+
text-decoration: underline;
29+
font-weight: 500;
30+
}
31+
32+
.md-banner a:hover {
33+
text-decoration: none;
34+
}
35+
36+
/* -------------------------------------------------------------------
37+
Version Admonitions
38+
------------------------------------------------------------------- */
39+
40+
/* New in version X.Y */
41+
.admonition.version-added {
42+
border-left-color: #00c853;
43+
}
44+
45+
.admonition.version-added > .admonition-title {
46+
background-color: rgba(0, 200, 83, 0.1);
47+
}
48+
49+
.admonition.version-added > .admonition-title::before {
50+
background-color: #00c853;
51+
content: "✨";
52+
}
53+
54+
/* Changed in version X.Y */
55+
.admonition.version-changed {
56+
border-left-color: #ff9800;
57+
}
58+
59+
.admonition.version-changed > .admonition-title {
60+
background-color: rgba(255, 152, 0, 0.1);
61+
}
62+
63+
.admonition.version-changed > .admonition-title::before {
64+
background-color: #ff9800;
65+
content: "🔄";
66+
}
67+
68+
/* Deprecated since version X.Y */
69+
.admonition.version-deprecated {
70+
border-left-color: #f44336;
71+
}
72+
73+
.admonition.version-deprecated > .admonition-title {
74+
background-color: rgba(244, 67, 54, 0.1);
75+
}
76+
77+
.admonition.version-deprecated > .admonition-title::before {
78+
background-color: #f44336;
79+
content: "⚠️";
80+
}
81+
82+
/* -------------------------------------------------------------------
83+
Inline Version Badges
84+
------------------------------------------------------------------- */
85+
86+
.version-badge {
87+
font-size: 0.7em;
88+
padding: 0.2em 0.5em;
89+
background-color: #2196F3;
90+
color: white;
91+
border-radius: 3px;
92+
font-weight: 500;
93+
vertical-align: middle;
94+
white-space: nowrap;
95+
}
96+
97+
.version-badge.deprecated {
98+
background-color: #f44336;
99+
}
100+
101+
.version-badge.new {
102+
background-color: #00c853;
103+
}
104+
105+
.version-badge.changed {
106+
background-color: #ff9800;
107+
}
108+
109+
/* -------------------------------------------------------------------
110+
Code Block Enhancements
111+
------------------------------------------------------------------- */
112+
113+
/* Add subtle visual distinction for code comparisons */
114+
.version-comparison {
115+
display: grid;
116+
grid-template-columns: 1fr 1fr;
117+
gap: 1rem;
118+
margin: 1rem 0;
119+
}
120+
121+
.version-comparison > div {
122+
padding: 0.5rem;
123+
border-radius: 0.2rem;
124+
}
125+
126+
.version-comparison .legacy {
127+
background-color: rgba(244, 67, 54, 0.05);
128+
border-left: 3px solid #f44336;
129+
}
130+
131+
.version-comparison .current {
132+
background-color: rgba(0, 200, 83, 0.05);
133+
border-left: 3px solid #00c853;
134+
}

‎src/index.md‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,32 @@
11
# DataJoint Documentation
22

3-
> **DataJoint 2.0 is a major breaking release.** Existing pipelines require migration.
4-
> See the [Migration Guide](how-to/migrate-to-v20.md) for upgrade instructions.
5-
> For pre-2.0 documentation, visit [datajoint.github.io/datajoint-python](https://datajoint.github.io/datajoint-python).
3+
!!! warning "DataJoint 2.0+ Documentation"
4+
5+
This documentation is for **DataJoint 2.0 and later**. All code examples use 2.0 syntax and APIs.
6+
7+
**Upgrading from pre-2.0 (0.14.x)?** Follow the [Migration Guide](how-to/migrate-to-v20.md) for step-by-step upgrade instructions.
8+
9+
**Legacy documentation:** For DataJoint 0.x documentation, visit [datajoint.github.io/datajoint-python](https://datajoint.github.io/datajoint-python).
10+
11+
## Which Version Am I Using?
12+
13+
??? question "How do I check my DataJoint version?"
14+
15+
```python
16+
import datajoint as dj
17+
print(dj.__version__)
18+
```
19+
20+
- **Version 2.0 or higher:** You're on the current version ✓
21+
- **Version 0.14.x or lower:** You're on legacy DataJoint
22+
23+
**What should I do?**
24+
25+
- **Learning DataJoint:** Use this documentation (2.0+)
26+
- **Existing pipeline on 0.x:** Follow the [Migration Guide](how-to/migrate-to-v20.md)
27+
- **Need 0.x documentation:** Visit [legacy docs](https://datajoint.github.io/datajoint-python)
28+
29+
## About DataJoint
630

731
**DataJoint** is a framework for scientific data pipelines built on the [Relational Workflow Model](explanation/relational-workflow-model.md)—a paradigm where your database schema is an executable specification of your workflow.
832

0 commit comments

Comments
 (0)