Skip to content

Commit 55b6b88

Browse files
MilagrosMarinMilagrosMarin
authored
Merge pull request datajoint#106 from datajoint/docs/versioning-indicators
docs: implement Phase 1 versioning indicators
2 parents 0d7e6c5 + 10b3ad8 commit 55b6b88

File tree

6 files changed

+288
-4
lines changed

6 files changed

+288
-4
lines changed

‎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: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
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+
**DataJoint 2.0 is the baseline.** Features and APIs introduced in 2.0 are documented without version markers, as they are the standard for this documentation.
10+
11+
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.
12+
13+
## Version Indicators
14+
15+
### Global Indicators
16+
17+
**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.
18+
19+
**Footer:** The footer shows which version of DataJoint this documentation covers.
20+
21+
### Feature-Level Indicators
22+
23+
Version admonitions are used for features introduced **after 2.0** (i.e., version 2.1 and later):
24+
25+
#### New Features
26+
27+
!!! version-added "New in 2.1"
28+
29+
This indicates a feature that was introduced after the 2.0 baseline.
30+
31+
**Example usage:**
32+
33+
!!! version-added "New in 2.1"
34+
35+
The `dj.Top` operator with ordering support was introduced in DataJoint 2.1.
36+
37+
**Note:** Features present in DataJoint 2.0 (the baseline) are not marked with version indicators.
38+
39+
#### Changed Behavior
40+
41+
!!! version-changed "Changed in 2.1"
42+
43+
This indicates behavior that changed in a post-2.0 release.
44+
45+
**Example usage:**
46+
47+
!!! version-changed "Changed in 2.1"
48+
49+
The `populate()` method now supports priority-based scheduling by default.
50+
51+
Use `priority=50` to control execution order when using `reserve_jobs=True`.
52+
53+
#### Deprecated Features
54+
55+
!!! version-deprecated "Deprecated in 2.1, removed in 3.0"
56+
57+
This indicates features that are deprecated and will be removed in future versions.
58+
59+
**Example usage:**
60+
61+
!!! version-deprecated "Deprecated in 2.1, removed in 3.0"
62+
63+
The `allow_direct_insert` parameter is deprecated. Use `dj.config['safemode']` instead.
64+
65+
**Note:** Features deprecated at the 2.0 baseline (coming from pre-2.0) are documented in the [Migration Guide](../how-to/migrate-to-v20.md) rather than with admonitions, since this documentation assumes 2.0 as the baseline.
66+
67+
### Inline Version Badges
68+
69+
For features introduced **after 2.0**, inline version badges may appear in API reference:
70+
71+
- `dj.Top()` <span class="version-badge">v2.1+</span> - Top N restriction with ordering
72+
- `some_method()` <span class="version-badge deprecated">deprecated</span> - Legacy method
73+
74+
**Note:** Methods and features present in DataJoint 2.0 (the baseline) do not have version badges.
75+
76+
## Checking Your Version
77+
78+
To check which version of DataJoint you're using:
79+
80+
```python
81+
import datajoint as dj
82+
print(dj.__version__)
83+
```
84+
85+
- **Version 2.0 or higher:** You're on the current version
86+
- **Version 0.14.x or lower:** You're on legacy DataJoint
87+
88+
## Migration Path
89+
90+
If you're upgrading from legacy DataJoint (pre-2.0):
91+
92+
1. **Review** the [What's New in 2.0](../explanation/whats-new-2.md) page to understand major changes
93+
2. **Follow** the [Migration Guide](../how-to/migrate-to-v20.md) for step-by-step upgrade instructions
94+
3. **Reference** this documentation for updated syntax and APIs
95+
96+
## Legacy Documentation
97+
98+
For DataJoint 0.x documentation, visit:
99+
100+
**[datajoint.github.io/datajoint-python](https://datajoint.github.io/datajoint-python)**
101+
102+
## Version History
103+
104+
| Version | Release Date | Major Changes |
105+
|---------|--------------|---------------|
106+
| 2.0 | 2026 | Redesigned fetch API, unified stores, per-table jobs, semantic matching |
107+
| 0.14.x | 2020-2025 | Legacy version with external storage |
108+
| 0.13.x | 2019 | Legacy version |
109+
110+
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/how-to/installation.md‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,12 @@
22

33
Install DataJoint Python and set up your environment.
44

5+
!!! warning "DataJoint 2.0+ Required"
6+
7+
This documentation is for **DataJoint 2.0 and later**. The PyPI and conda releases for DataJoint 2.0 are currently in preparation.
8+
9+
**If you install now, you may get an older version (0.14.x).** After installation, verify you have version 2.0 or later before following the tutorials and guides.
10+
511
## Basic Installation
612

713
```bash
@@ -23,19 +29,35 @@ pip install datajoint[all]
2329

2430
## Development Installation
2531

32+
To install the latest pre-release version:
33+
2634
```bash
27-
git clone https://github.com/datajoint/datajoint-python.git
35+
git clone -b pre/v2.0 https://github.com/datajoint/datajoint-python.git
2836
cd datajoint-python
2937
pip install -e ".[dev]"
3038
```
3139

3240
## Verify Installation
3341

42+
**Important:** Check that you have DataJoint 2.0 or later:
43+
3444
```python
3545
import datajoint as dj
3646
print(dj.__version__)
3747
```
3848

49+
**Expected output:** `2.0.0` or higher
50+
51+
!!! danger "Version Mismatch"
52+
53+
If you see version `0.14.x` or lower, you have the legacy version of DataJoint. This documentation will not match your installed version.
54+
55+
**Options:**
56+
57+
1. **Upgrade to 2.0 (pre-release):** Install from the `pre/v2.0` branch (see Development Installation above)
58+
2. **Use legacy documentation:** Visit [datajoint.github.io/datajoint-python](https://datajoint.github.io/datajoint-python)
59+
3. **Migrate existing pipeline:** Follow the [Migration Guide](migrate-to-v20.md)
60+
3961
## Database Server
4062

4163
DataJoint requires a MySQL-compatible database server:

‎src/index.md‎

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

3-
> **DataJoint 2.0 is a major 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+
!!! info "Documentation for DataJoint 2.0+"
4+
5+
Python code examples in this documentation use DataJoint 2.0 syntax. If you're using DataJoint pre-2.0, see the [Migration Guide](how-to/migrate-to-v20.md) or visit [legacy docs](https://datajoint.github.io/datajoint-python).
6+
7+
## About DataJoint
68

79
**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.
810

0 commit comments

Comments
 (0)