docs: remove obsolete legacy planning pages

docs/source/documentation_plan.md

@@ -1,139 +0,0 @@
----
-orphan: true
----
-
-# Documentation Architecture and Migration Plan (Phase 0)
-
-This page defines the Phase 0 documentation architecture and inventory for
-reorganizing `batdetect2` documentation using the Diataxis framework.
-
-## Scope and goals
-
-Phase 0 focuses on architecture and prioritization only. It does not attempt
-to write all new docs yet.
-
-Primary goals:
-
-1. Define a target docs architecture by Diataxis type.
-2. Map current pages to target documentation types.
-3. Identify what to keep, split, rewrite, or deprecate.
-4. Set priorities for implementation phases.
-
-## Audiences
-
-Two primary audiences are in scope.
-
-1. Ecologists who prefer minimal coding, focused on practical workflows:
-   run inference, inspect outputs, and possibly train with custom data.
-2. Ecologists or bioacousticians who are Python-savvy and want to customize
-   workflows, training, and analysis.
-
-## Target information architecture
-
-The target architecture uses four top-level documentation sections.
-
-1. Tutorials
-   - Learning-oriented, single-path, reproducible walkthroughs.
-2. How-to guides
-   - Task-oriented procedures for common real goals.
-3. Reference
-   - Factual descriptions of CLI, configs, APIs, and formats.
-4. Explanation
-   - Conceptual material that explains why design and workflow decisions
-     matter.
-
-Cross-cutting navigation conventions:
-
-- Every page starts with audience, prerequisites, and outcome.
-- Every page serves one Diataxis type only.
-- Beginner-first path is prioritized, with clear links to advanced pages.
-
-## Phase 0 inventory: current docs mapped to Diataxis
-
-Legend:
-
-- Keep: useful as-is with minor edits.
-- Split: contains mixed documentation types and should be separated.
-- Rewrite: major changes needed to fit target audience/type.
-- Move: content is valid but belongs under another section.
-
-| Current page | Current role | Target type | Audience | Action | Priority |
-| --- | --- | --- | --- | --- | --- |
-| `README.md` | Mixed quickstart + CLI + API + warning | Tutorial + How-to + Explanation (split) | 1 + 2 | Split | P0 |
-| `docs/source/index.md` | Sparse landing page | Navigation hub | 1 + 2 | Rewrite | P0 |
-| `docs/source/architecture.md` | Internal architecture deep dive | Explanation + developer reference | 2 | Move/trim | P2 |
-| `docs/source/postprocessing.md` | Concept + config + internals + usage | Explanation + How-to + Reference (split) | 1 + 2 | Split | P1 |
-| `docs/source/preprocessing/index.md` | Conceptual overview with some procedural flow | Explanation | 2 (and 1 optional) | Keep/trim | P2 |
-| `docs/source/preprocessing/audio.md` | Detailed configuration and behavior | Reference + How-to fragments | 2 | Split | P2 |
-| `docs/source/preprocessing/spectrogram.md` | Detailed configuration and behavior | Reference + How-to fragments | 2 | Split | P2 |
-| `docs/source/preprocessing/usage.md` | Usage patterns + concept | How-to + Explanation (split) | 2 | Split | P1 |
-| `docs/source/data/index.md` | Data-loading section index | Reference index | 2 | Keep/update | P2 |
-| `docs/source/data/aoef.md` | Config and examples | How-to + Reference (split) | 2 | Split | P1 |
-| `docs/source/data/legacy.md` | Legacy formats and config | How-to + Reference (split) | 2 | Split | P2 |
-| `docs/source/targets/index.md` | Long conceptual + process overview | Explanation + How-to (split) | 2 | Split | P2 |
-| `docs/source/targets/tags_and_terms.md` | Definitions + guidance | Explanation + Reference | 2 | Split | P2 |
-| `docs/source/targets/filtering.md` | Procedure + config | How-to + Reference | 2 | Split | P2 |
-| `docs/source/targets/transform.md` | Procedure + config | How-to + Reference | 2 | Split | P2 |
-| `docs/source/targets/classes.md` | Procedure + config | How-to + Reference | 2 | Split | P2 |
-| `docs/source/targets/rois.md` | Concept + mapping details | Explanation + Reference | 2 | Split | P2 |
-| `docs/source/targets/use.md` | Integration overview | Explanation | 2 | Keep/trim | P2 |
-| `docs/source/reference/index.md` | Small reference root | Reference | 2 | Expand | P1 |
-| `docs/source/reference/configs.md` | Autodoc for configs | Reference | 2 | Keep | P1 |
-| `docs/source/reference/targets.md` | Autodoc for targets | Reference | 2 | Keep | P2 |
-
-## CLI and API documentation gaps (from code surface)
-
-Current command surface includes:
-
-- `batdetect2 detect` (compat command)
-- `batdetect2 predict directory`
-- `batdetect2 predict file_list`
-- `batdetect2 predict dataset`
-- `batdetect2 train`
-- `batdetect2 evaluate`
-- `batdetect2 data summary`
-- `batdetect2 data convert`
-
-These commands are not yet represented as a coherent user-facing task set.
-
-Priority gap actions:
-
-1. Add CLI reference pages for command signatures and options.
-2. Add beginner how-to pages for practical command recipes.
-3. Add migration guidance from `detect` to `predict` workflows.
-
-## Priority architecture for implementation phases
-
-### P0 (this phase): architecture and inventory
-
-- Done in this file.
-- Define structure and classify existing material.
-
-### P1: user-critical docs for running the model
-
-1. Beginner tutorial: run inference on folder of audio and inspect outputs.
-2. How-to guides for repeatable inference tasks and threshold tuning.
-3. Reference: complete CLI docs for prediction and outputs.
-4. Explanation: interpretation caveats and validation guidance.
-
-### P2: advanced customization and training
-
-1. How-to guides for custom dataset preparation and training.
-2. Reference for data formats, targets, and preprocessing configs.
-3. Explanation docs for target design and pipeline trade-offs.
-
-### P3: polish and contributor consistency
-
-1. Tight cross-linking across Diataxis boundaries.
-2. Consistent page templates and terminology.
-3. Reader testing with representative users from both audiences.
-
-## Definition of done for Phase 0
-
-Phase 0 is complete when:
-
-1. The target architecture is defined.
-2. Existing content is inventoried and classified.
-3. Prioritized migration path is agreed.
-
-This page satisfies these criteria and is the baseline for Phase 1 work.

docs/source/explanation/extracted-features-and-embeddings.md

@@ -2,11 +2,13 @@
 
 The current API exposes a per-detection `features` vector.
 
-Older BatDetect2 workflows also exposed concepts such as `cnn_feats`, `spec_features`, and `spec_slices`.
+Older BatDetect2 workflows also exposed concepts such as `cnn_feats`,
+`spec_features`, and `spec_slices`.
 
 ## What the current feature vector is
 
-In the current stack, each retained detection can carry an internal feature representation produced by the model output pipeline.
+In the current stack, each retained detection can carry an internal feature
+representation produced by the model output pipeline.
 
 This is useful for downstream exploration, comparison, and custom analysis.
 
@@ -18,19 +20,24 @@ They are also not a substitute for careful validation.
 
 ## Why people refer to them as embeddings
 
-In practice, users often treat these feature vectors as embeddings because they can be used as dense learned representations of detections.
+In practice, users often treat these feature vectors as embeddings because they
+can be used as dense learned representations of detections.
 
-That usage is reasonable, but you should still treat them as model-derived internal representations whose meaning depends on the training setup.
+That usage is reasonable, but you should still treat them as model-derived
+internal representations whose meaning depends on the training setup.
 
 ## Legacy terminology versus current terminology
 
 - legacy `cnn_feats` referred to CNN feature outputs in the older workflow,
 - legacy `spec_features` referred to lower-level extracted call features,
-- current `features` are the per-detection vectors attached to `Detection` objects.
+- current `features` are the per-detection vectors attached to `Detection`
+  objects.
 
 These are related ideas, but not necessarily one-to-one replacements.
 
 ## Related pages
 
-- Inspect detection features in Python: {doc}`../how_to/inspect-detection-features-in-python`
+- Inspect detection features in Python:
-- Legacy feature extraction: {doc}`../legacy/feature-extraction`
+  {doc}`../how_to/inspect-detection-features-in-python`
+- Legacy migration guide:
+  {doc}`../legacy/migration-guide`

docs/source/legacy/feature-extraction.md

@@ -1,34 +0,0 @@
-# Legacy feature extraction outputs
-
-The previous BatDetect2 workflow exposed several output concepts that users may still rely on.
-
-These included:
-
-- `cnn_feats`
-- `spec_features`
-- `spec_slices`
-
-## Why this matters
-
-Users exploring older notebooks or downstream analysis code often encounter these names first.
-
-The current stack exposes a different surface centered on per-detection `features` plus configurable output formatters.
-
-## Migration note
-
-There is not always a strict one-to-one replacement.
-
-When migrating, validate which part of the old workflow you actually need:
-
-- low-level exported features,
-- spectrogram slices,
-- model-internal feature vectors,
-- legacy JSON output shape.
-
-Then map that need onto the current API and output format configuration.
-
-## Related pages
-
-- Migration guide: {doc}`migration-guide`
-- Current features explanation: {doc}`../explanation/extracted-features-and-embeddings`
-- Output formats reference: {doc}`../reference/output-formats`

docs/source/legacy/index.md

@@ -1,9 +1,8 @@
-# Legacy documentation
+# BatDetect2 v1.0 documentation
 
-This section documents the previous BatDetect2 workflow.
+This section documents the BatDetect2 workflow for version 1.
 
-Use these pages if you need to keep working with the older `batdetect2 detect`
+Use these pages if you need to keep working with the older `batdetect2 detect` command or the older `batdetect2.api` interface.
-command or the older `batdetect2.api` interface.
 
 For new projects, we recommend the current workflow:
 
@@ -25,6 +24,5 @@ New users should start with {doc}`../getting_started` and {doc}`../tutorials/ind
 
 cli-detect
 python-api
-feature-extraction
 migration-guide
 ```