docs: landing page and README improvements (datajoint#105)

* docs: remove 'breaking' from landing page announcement

Changed 'major breaking release' to 'major release'

* docs: update migration guide links in README

- Changed migrate-from-0x.md to migrate-to-v20.md (2 references)
- Ensures README points to correct migration guide file

* docs: simplify README - remove redundancy, reference live docs

- Removed Quick Start section (covered on docs.datajoint.com)
- Condensed local development instructions
- Simplified Contributing, Related, Citation sections
- Reduced from ~310 lines to ~87 lines
- Focus README on repo structure and contributing, not usage docs

* docs: add license history note (LGPLv2.1 prior to v2.0)

* docs: address reviewer feedback on README

- Separate git clone commands for clarity (line 30-31)
- Add BUILD mode example comment (line 37-38)
- Add Windows venv activation comment (line 51)
- Use clearer placeholder credentials (line 56-57)
- Add chmod 600 for secrets security (line 58)
- Fix citation link trailing slash consistency (line 86)

Author: dimitri-yatsenko

README.md

@@ -1,310 +1,91 @@
 # DataJoint Documentation
 
-Official documentation for [DataJoint](https://github.com/datajoint/datajoint-python) 2.0,
-an open-source framework for building scientific data pipelines.
+Official documentation for [DataJoint](https://github.com/datajoint/datajoint-python) 2.0 — an open-source framework for building scientific data pipelines.
 
-**Live site:** https://docs.datajoint.com
+**📖 Live site:** https://docs.datajoint.com
 
-> **📘 Upgrading from legacy DataJoint (pre-2.0)?**
-> See the **[Migration Guide](https://docs.datajoint.com/how-to/migrate-from-0x/)** for a step-by-step upgrade path.
+> **Upgrading from pre-2.0?** See the [Migration Guide](https://docs.datajoint.com/how-to/migrate-to-v20/)
 
-## What is DataJoint?
+## About DataJoint
 
-DataJoint is a Python framework for building scientific data pipelines using relational
-databases. It implements the **Relational Workflow Model**—a paradigm that extends
-relational databases with native support for computational workflows.
-
-Key features:
-
-- **Declarative schema design** — Define tables and relationships in Python
-- **Automatic dependency tracking** — Foreign keys encode workflow dependencies
-- **Built-in computation** — Imported and Computed tables run automatically
-- **Data integrity** — Referential integrity and transaction support
-- **Reproducibility** — Immutable data with full provenance
-
-## Quick Start
-
-### Installation
-
-```bash
-pip install datajoint
-```
-
-For schema diagrams, install Graphviz (the system library, not just Python bindings):
-
-```bash
-# macOS
-brew install graphviz
-
-# Ubuntu/Debian
-sudo apt-get install graphviz libgraphviz-dev
-
-# conda (any platform)
-conda install -c conda-forge graphviz pygraphviz
-```
-
-If using pip (after installing system Graphviz):
-```bash
-pip install pygraphviz
-```
-
-### Configuration
-
-DataJoint uses configuration files to manage database credentials securely. Create these
-files in your project directory:
-
-**datajoint.json** (non-sensitive settings, commit to version control):
-```json
-{
-  "database": {
-    "host": "localhost",
-    "port": 3306
-  }
-}
-```
-
-**.secrets/database.user** and **.secrets/database.password** (sensitive, add to .gitignore):
-```bash
-mkdir -p .secrets
-echo "your_username" > .secrets/database.user
-echo "your_password" > .secrets/database.password
-chmod 600 .secrets/*
-echo ".secrets/" >> .gitignore
-```
-
-DataJoint automatically discovers these files by searching up from the current directory.
-This keeps credentials out of your code and version control.
-
-### Define a Schema
-
-```python
-import datajoint as dj
-
-schema = dj.Schema('my_pipeline')
-
-@schema
-class Subject(dj.Manual):
-    definition = """
-    subject_id : int32
-    ---
-    name : varchar(100)
-    date_of_birth : date
-    """
-
-@schema
-class Session(dj.Manual):
-    definition = """
-    -> Subject
-    session_idx : int32
-    ---
-    session_date : date
-    duration : float32          # minutes
-    notes = '' : varchar(1000)
-    """
-
-@schema
-class ProcessedData(dj.Computed):
-    definition = """
-    -> Session
-    ---
-    result : float64
-    """
-
-    def make(self, key):
-        # Compute result from session data
-        duration = (Session & key).fetch1('duration')
-        self.insert1({**key, 'result': duration * 2})
-```
-
-Note: Use DataJoint core types (`int32`, `float32`, `float64`, `varchar`) for portability
-across database backends.
-
-### View Schema Diagram
-
-```python
-dj.Diagram(schema)
-```
-
-### Run Computations
-
-```python
-ProcessedData.populate()
-```
+DataJoint is a Python framework for scientific data pipelines built on the **Relational Workflow Model**. For installation, tutorials, and complete documentation, visit **[docs.datajoint.com](https://docs.datajoint.com)**.
 
 ## Documentation Structure
 
-This documentation follows the [Diátaxis](https://diataxis.fr/) framework:
-
-| Section | Purpose | Link |
-|---------|---------|------|
-| **Tutorials** | Learn by building real pipelines | [src/tutorials/](src/tutorials/) |
-| **How-To Guides** | Practical guides for common tasks | [src/how-to/](src/how-to/) |
-| **Explanation** | Understand the principles behind DataJoint | [src/explanation/](src/explanation/) |
-| **Reference** | Specifications and API documentation | [src/reference/](src/reference/) |
+This repository contains the source for the DataJoint documentation, organized using the [Diátaxis](https://diataxis.fr/) framework:
 
-Key pages:
-- **[Migration Guide](src/how-to/migrate-from-0x.md)** — Upgrade from legacy DataJoint (pre-2.0)
-- **[What's New in 2.0](src/explanation/whats-new-2.md)** — Major changes and improvements
+- **[Tutorials](https://docs.datajoint.com/tutorials/)** — Learn by building real pipelines
+- **[How-To Guides](https://docs.datajoint.com/how-to/)** — Practical task-oriented guides
+- **[Explanation](https://docs.datajoint.com/explanation/)** — Understanding concepts and design
+- **[Reference](https://docs.datajoint.com/reference/)** — Specifications and API documentation
 
-## Local Development with Docker (Recommended)
+## Local Development
 
-The Docker environment includes MySQL, MinIO (S3-compatible storage), Graphviz, and all
-dependencies needed to build documentation and execute tutorial notebooks.
-
-### Start the Environment
+### Docker (Recommended)
 
 ```bash
-# Clone the documentation repository
+# Clone repositories
 git clone https://github.com/datajoint/datajoint-docs.git
 cd datajoint-docs
-
-# Clone datajoint-python pre-release branch (required for API docs)
 cd ..
 git clone -b pre/v2.0 https://github.com/datajoint/datajoint-python.git
 cd datajoint-docs
 
-# Start all services (MySQL, MinIO, docs server)
+# Start live preview at http://localhost:8000
 MODE="LIVE" docker compose up --build
-```
-
-Navigate to http://127.0.0.1:8000/
-
-### Services
-
-| Service | Port | Description |
-|---------|------|-------------|
-| `docs` | 8000 | MkDocs live server |
-| `mysql` | 3306 | MySQL 8.0 database |
-| `minio` | 9002 | MinIO S3 API |
-| `minio` | 9003 | MinIO console |
-
-### Execute Tutorial Notebooks
-
-Tutorial notebooks can be executed inside the Docker environment where the database
-is available:
 
-```bash
-# Execute a single notebook
-docker compose exec docs jupyter nbconvert \
-    --to notebook --execute --inplace \
-    /main/src/tutorials/01-getting-started.ipynb
-
-# Execute all tutorials
-docker compose exec docs bash -c '
-    for nb in /main/src/tutorials/*.ipynb; do
-        jupyter nbconvert --to notebook --execute --inplace "$nb"
-    done
-'
+# Build static site (optional)
+# MODE="BUILD" docker compose up --build
 ```
 
-### Build Static Site
+The Docker environment includes MySQL, MinIO, and all dependencies.
 
-```bash
-# Build static HTML (output in site/)
-MODE="BUILD" docker compose up --build
-```
+### Native Python
 
-### Reset Database
+**Prerequisites:** Python 3.10+, MySQL 8.0+
 
 ```bash
-# Stop services and remove data volumes
-docker compose down -v
-```
-
-## Local Development without Docker
-
-### Prerequisites
-
-- Python 3.10+
-- MySQL 8.0+ (running locally)
-- Graphviz (for schema diagrams)
-
-### Setup
-
-```bash
-# Clone the repository
+# Setup
 git clone https://github.com/datajoint/datajoint-docs.git
 cd datajoint-docs
-
-# Create virtual environment
-python -m venv .venv
-source .venv/bin/activate  # or .venv\Scripts\activate on Windows
-
-# Install dependencies
+python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
 pip install -r pip_requirements.txt
-```
-
-Note: For schema diagrams, ensure Graphviz system libraries are installed (see Quick Start).
 
-### Configure Database Connection
-
-The repository includes a `datajoint.json` with default settings. Create the secrets
-directory with your credentials:
-
-```bash
+# Configure credentials
 mkdir -p .secrets
 echo "your_username" > .secrets/database.user
 echo "your_password" > .secrets/database.password
 chmod 600 .secrets/*
-```
-
-### Preview Documentation
 
-```bash
+# Start live preview at http://localhost:8000
 mkdocs serve
 ```
 
-Navigate to http://127.0.0.1:8000/
-
 ## Contributing
 
-Contributions are welcome! See our [contribution guidelines](src/about/contributing.md).
-
-### Quick Fixes
-
-1. Fork the repository
-2. Edit the relevant markdown file in `src/`
-3. Submit a pull request
-
-### Larger Changes
+Contributions welcome! See [contribution guidelines](https://docs.datajoint.com/about/contributing/).
 
-1. Open an issue to discuss the change
-2. Fork and create a feature branch
-3. Make changes with `mkdocs serve` for preview
-4. Submit a pull request
-
-### Executing Notebooks for CI
-
-When modifying tutorial notebooks, re-execute them to update outputs:
+**Quick fixes:** Fork, edit markdown in `src/`, submit PR.
 
+**Tutorial notebooks:** Re-execute after changes:
 ```bash
-docker compose exec docs jupyter nbconvert \
-    --to notebook --execute --inplace \
-    --ExecutePreprocessor.timeout=300 \
+docker compose exec docs jupyter nbconvert --to notebook --execute --inplace \
     /main/src/tutorials/YOUR_NOTEBOOK.ipynb
 ```
 
-## Related Repositories
+## Related
 
-- **[datajoint-python](https://github.com/datajoint/datajoint-python)** — Core DataJoint library
-- **[DataJoint Elements](https://datajoint.com/docs/elements/)** — Neuroscience pipeline elements
-- **[DataJoint Works](https://datajoint.com)** — Company and commercial support
+- [datajoint-python](https://github.com/datajoint/datajoint-python) — Core library
+- [DataJoint Elements](https://docs.datajoint.com/elements/) — Neuroscience pipeline modules
+- [datajoint.com](https://datajoint.com) — Commercial support
 
 ## Citation
 
-If you use DataJoint in your research, please cite:
-
-> Yatsenko D, Walker EY, Tolias AS. DataJoint: A Simpler Relational Data Model.
-> arXiv:2303.00102. 2023. doi: [10.48550/arXiv.2303.00102](https://doi.org/10.48550/arXiv.2303.00102)
+> Yatsenko D, Walker EY, Tolias AS. DataJoint: A Simpler Relational Data Model. arXiv:2303.00102. 2023. doi: [10.48550/arXiv.2303.00102](https://doi.org/10.48550/arXiv.2303.00102)
 
-Earlier publication:
-
-> Yatsenko D, Reimer J, Ecker AS, Walker EY, Sinz F, Berens P, Hoenselaar A,
-> Cotton RJ, Siapas AS, Tolias AS. DataJoint: managing big scientific data
-> using MATLAB or Python. bioRxiv. 2015. doi: [10.1101/031658](https://doi.org/10.1101/031658)
+Full citation information: [docs.datajoint.com/about/citation/](https://docs.datajoint.com/about/citation/)
 
 ## License
 
-Documentation: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
-
-DataJoint software: [Apache 2.0](https://github.com/datajoint/datajoint-python/blob/master/LICENSE)
+- Documentation: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+- DataJoint software: [Apache 2.0](https://github.com/datajoint/datajoint-python/blob/master/LICENSE) (LGPLv2.1 prior to v2.0)

src/index.md

@@ -1,6 +1,6 @@
 # DataJoint Documentation
 
-> **DataJoint 2.0 is a major breaking release.** Existing pipelines require migration.
+> **DataJoint 2.0 is a major release.** Existing pipelines require migration.
 > See the [Migration Guide](how-to/migrate-to-v20.md) for upgrade instructions.
 > For pre-2.0 documentation, visit [datajoint.github.io/datajoint-python](https://datajoint.github.io/datajoint-python).