docs: reorganize testing documentation and add file placement guidelines

yarikoptic · yarikoptic · commit 5c365537c7e0 · 2026-01-30T18:49:15.000-05:00
- Add comprehensive testing guide to Sphinx docs (docs/source/development/testing.rst)
- Add contributing guide to Sphinx docs (docs/source/development/contributing.rst)
- Update CLAUDE.md with file placement guidelines to prevent root clutter
- Update DEVELOPMENT.md to reference new Sphinx documentation
- Add .lad/tmp/ to .gitignore for LAD session artifacts
- Integrate development docs into main Sphinx documentation index

This improves documentation organization and prevents temporary files
from cluttering the project root. LAD-generated analysis files now go
to .lad/tmp/, while permanent documentation goes to docs/source/.

Testing documentation now properly integrated with Sphinx for better
searchability and navigation.
diff --git a/.gitignore b/.gitignore
@@ -16,3 +16,4 @@ sandbox/
 venv/
 venvs/
 .DS_Store
+.lad/tmp/
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,6 +2,8 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+For comprehensive development information, see `DEVELOPMENT.md` and the developer documentation in `docs/source/development/`.
+
 ## Build/Test Commands
 - Run tests: `tox -e py3` but should also work with just `python -m pytest dandi` if in a venv
 - Tests which require an instance of the archive, would use a fixture to start on using docker-compose.
@@ -35,3 +37,21 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Documentation
 - Keep docstrings updated when changing function signatures
 - CLI help text should be clear and include examples where appropriate
+- Documentation files go in `docs/source/` (Sphinx RST format)
+- Testing documentation: See `.lad/tmp/TESTING_BEST_PRACTICES.md` and `.lad/tmp/TESTING_GUIDELINES.md`
+
+## File Placement Guidelines
+**IMPORTANT**: Do not create analysis, baseline, or temporary files in the project root.
+
+Proper file locations:
+- **LAD session artifacts**: `.lad/tmp/` (test baselines, analysis reports, session notes)
+- **Documentation**: `docs/source/` (must be RST format for Sphinx)
+- **Test data**: `dandi/tests/data/`
+- **Development notes**: `.lad/tmp/notes/` or personal notes outside the repo
+- **Temporary scratch files**: Use system temp dir or `.lad/tmp/scratchpad/`
+
+Examples of files that should NOT be in project root:
+- ❌ `test_execution_baseline.md` → ✅ `.lad/tmp/test_execution_baseline.md`
+- ❌ `analysis_report.md` → ✅ `.lad/tmp/analysis_report.md`
+- ❌ `session_notes.txt` → ✅ `.lad/tmp/notes/session_notes.txt`
+- ❌ `TESTING_GUIDE.md` → ✅ `docs/source/development/testing.rst` (converted to RST)
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -1,5 +1,7 @@
 # DANDI Client Development
 
+> **Note**: For comprehensive developer documentation including testing guides and contribution workflows, see `docs/source/development/` (built Sphinx docs) or the [online documentation](https://dandi.readthedocs.io/).
+
 ## Development environment
 
 Assuming that you have `python3` (and virtualenv) installed, the fastest
@@ -159,3 +161,19 @@ organized by label.  `auto` recognizes the following PR labels:
 - `tests` — for changes to tests
 - `dependencies` — for updates to dependency versions
 - `performance` — for performance improvements
+
+## Developer Documentation
+
+For additional developer resources, see the Sphinx documentation in `docs/source/development/`:
+
+- **Testing Guide** (`docs/source/development/testing.rst`) - Comprehensive testing practices, patterns, and Docker setup
+- **Contributing Guide** (`docs/source/development/contributing.rst`) - Quick reference for contribution workflow
+
+To build the documentation locally:
+```bash
+cd docs
+make html
+open build/html/index.html  # or xdg-open on Linux
+```
+
+Or view online at [dandi.readthedocs.io](https://dandi.readthedocs.io/)
diff --git a/docs/source/development/contributing.rst b/docs/source/development/contributing.rst
@@ -0,0 +1,128 @@
+.. _contributing:
+
+**********************
+Contributing Guide
+**********************
+
+Thank you for your interest in contributing to dandi-cli!
+
+This document provides a quick overview. For comprehensive details, see ``DEVELOPMENT.md`` in the repository root.
+
+Getting Started
+===============
+
+1. **Fork and clone** the repository
+2. **Set up development environment**:
+
+   .. code-block:: bash
+
+      # Using uv (recommended)
+      uv venv
+      source .venv/bin/activate
+      uv pip install -e ".[devel]"
+
+      # Or using traditional venv
+      python -m venv venvs/dev3
+      source venvs/dev3/bin/activate
+      pip install -e ".[devel]"
+
+3. **Install pre-commit hooks**:
+
+   .. code-block:: bash
+
+      pre-commit install
+
+4. **Run tests** to verify setup:
+
+   .. code-block:: bash
+
+      pytest dandi/tests/test_utils.py -v
+
+
+Development Workflow
+====================
+
+1. **Create a branch** for your feature or bugfix
+2. **Write tests first** (TDD approach recommended)
+3. **Implement your changes**
+4. **Run tests and linters**:
+
+   .. code-block:: bash
+
+      # Run tests
+      pytest dandi -x
+
+      # Run linters
+      tox -e lint,typing
+
+5. **Commit your changes**:
+
+   .. code-block:: bash
+
+      git add .
+      git commit -m "feat: add new feature"
+
+   If pre-commit hooks modify files, just commit again.
+
+6. **Push and create a Pull Request**
+
+
+Code Style
+==========
+
+- **Formatter**: Black (line length 100)
+- **Import sorting**: isort (profile="black")
+- **Type annotations**: Required for new code
+- **Docstrings**: NumPy style for public APIs
+- **Naming**:
+  - Classes: ``CamelCase``
+  - Functions/variables: ``snake_case``
+  - Exceptions: End with "Error" (e.g., ``ValidateError``)
+
+
+Testing Requirements
+====================
+
+- All new features must include tests
+- Bug fixes should include regression tests
+- Mark AI-generated tests with ``@pytest.mark.ai_generated``
+- New pytest markers must be registered in ``tox.ini``
+
+See :doc:`testing` for comprehensive testing guidelines.
+
+
+Pull Request Guidelines
+=======================
+
+- **Title**: Use conventional commit format (``feat:``, ``fix:``, ``docs:``, etc.)
+- **Description**: Explain what and why, not how
+- **Tests**: Ensure all tests pass
+- **Documentation**: Update docstrings and docs as needed
+- **Changelog**: Will be auto-generated from PR labels
+
+
+Code Review Process
+===================
+
+1. CI must pass (tests, linting, type checking)
+2. At least one maintainer approval required
+3. Address review feedback
+4. Squash commits if requested
+5. Maintainer will merge when ready
+
+
+Communication
+=============
+
+- **Issues**: Report bugs and request features on GitHub
+- **Discussions**: Use GitHub Discussions for questions
+- **Pull Requests**: For code contributions
+
+
+Additional Resources
+====================
+
+- ``DEVELOPMENT.md`` - Detailed development guide
+- ``CLAUDE.md`` - Project-specific guidelines for AI assistants
+- :doc:`testing` - Comprehensive testing guide
+- `Contributing to Open Source <https://opensource.guide/how-to-contribute/>`_ - General guide
diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst
@@ -0,0 +1,24 @@
+.. _development:
+
+*******************
+Development Guide
+*******************
+
+This section contains guides for contributing to dandi-cli.
+
+.. toctree::
+   :maxdepth: 2
+
+   testing
+   contributing
+
+
+Testing Guide
+=============
+
+See :doc:`testing` for comprehensive testing guidelines and best practices.
+
+Contributing
+============
+
+See :doc:`contributing` for general contribution guidelines.
diff --git a/docs/source/development/testing.rst b/docs/source/development/testing.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
