feat: improve docs

ImperialCollegeLondon · Nov 21, 2024 · 9a7b0ef · 9a7b0ef
1 parent 6e20f86
commit 9a7b0ef
Showing 1 changed file with 155 additions and 101 deletions.
diff --git a/docs/documentation.md b/docs/documentation.md
@@ -1,93 +1,90 @@
-# Documentation
+# DinoSoft Documentation
 
-> **About**
-> DinoSoft is a Python library for paleontological data analysis, specializing in dinosaur fossil processing and ecological modeling.
+DinoSoft is a Python library for paleontological data analysis, specializing in dinosaur fossil processing and ecological modeling.
+
+## Documentation Types
+
+### Tutorials
+
+Learn DinoSoft step-by-step
+
+[Start Learning](#getting-started-with-dinosoft)
+
+### How-To Guides
+
+Task-focused guides for specific goals
+
+[View Guides](#installing-dinosoft)
+
+### Reference
+
+Complete API and configuration documentation
+
+[Read Reference](#core-features-reference)
+
+### Roadmap
+
+Understand roadmap and support options
+
+[Learn More](#roadmap-and-support)
 
 ## Key Features
 
-- **Fossil Analysis**
-    Process and analyze fossil specimens using our advanced ML pipeline
-    [Get Started](https://example.com)
+### Fossil Analysis
 
-- **Genetic Studies**
-    DNA preservation analysis and ancient genome reconstruction
-    [Learn More](https://example.com)
+Process and analyze fossil specimens using our advanced ML pipeline
 
-- **Morphology**
-    Complete morphological analysis and comparison tools
-    [Explore](https://example.com)
+[Get Started](#getting-started-with-dinosoft)
 
-- **Statistics**
-    Statistical analysis and visualization tools
-    [View Details](https://example.com)
+### Genetic Studies
 
-## Installation Guide
+DNA preservation analysis and ancient genome reconstruction
 
-### System Requirements
+[Learn More](#core-features-reference)
 
-> **Prerequisites**
-> - Python 3.8 or higher
-> - 4GB RAM minimum
-> - CUDA-compatible GPU recommended
+### Morphology
 
-### Installation Methods
+Complete morphological analysis and comparison tools
 
-**pip (Recommended)**
+[Explore](#core-features-reference)
 
-Set up a virtual environment, or if done simply run `pip`.
-```bash
-python -m venv dinoenv
-source dinoenv/bin/activate  # Linux/Mac
-pip install dinosoft
-```
+### Statistics
 
-Available extras:
-```bash
-pip install dinosoft[viz]     # Visualization tools
-pip install dinosoft[ml]      # Machine learning features
-pip install dinosoft[full]    # All optional dependencies
-```
+Statistical analysis and visualization tools
 
-**conda**
-```bash
-conda create -n dinoenv python=3.9
-conda activate dinoenv
-conda install -c paleochannel dinosoft
-```
+[View Details](#using-dinosoft)
 
-**Development**
-```bash
-git clone https://github.com/dinosoft/dinosoft.git
-cd dinosoft
-pip install -e ".[dev]"
-```
+[Install DinoSoft today](#installing-dinosoft)
 
-> **Common Issues**
->
-> - **ImportError**: Check Python version compatibility
-> - **GPU not detected**: Verify CUDA installation
-> - **Memory Error**: Increase available RAM
+## Getting Started with DinoSoft
 
-## Quick Start
+This tutorial will guide you through your first fossil analysis using DinoSoft.
 
 ```python
 import dinosoft as ds
 
-# Loads specimen data from common museum catalog formats
+# Load a fossil specimen
 specimen = ds.load_specimen('KU45690')
-# Performs morphological analysis
 analysis = ds.analyze_specimen(specimen)
-# Generates publication-ready visualizations
 ds.visualize(analysis)
 ```
 
-## Core Features
+### Next Steps
+
+Once you've completed your first analysis, learn about:
+
+- [Configuring analysis settings](#configuration-reference)
+- [Working with populations](#core-features-reference)
+- [Creating custom visualizations](#advanced-examples)
+
+## Core Features Reference
 
 DinoSoft offers three primary data structures:
 
-**Species**
-Represents a single dinosaur species with complete taxonomic and ecological data
+`Species`
 
+Represents a single dinosaur species with complete taxonomic and ecological data
+
 ```python
 tyrannosaurus = ds.Species({
     "name": "Tyrannosaurus rex",
@@ -97,16 +94,18 @@ tyrannosaurus = ds.Species({
 })
 ```
 
-**Population**
-Models population dynamics and ecological interactions
+`Population`
 
+Models population dynamics and ecological interactions
+
 ```python
 population = ds.Population(tyrannosaurus, 
                          territory_km2=1000, 
                          prey_density=0.5)
 ```
 
-**Time Period**
+`Period`
+
 Creates a period using standardized geological time periods
 
 ```python
@@ -117,19 +116,91 @@ custom_period = ds.Period(
 )
 ```
 
+## Configuration Reference
+
+Create `dinosoft.yml` in your project root:
+
+```yaml
+analysis:
+  settings:
+    precision: high     # Analysis precision
+    units: metric      # Measurement units
+  visualization:
+    style: journal     # Publication style
+    colormap: viridis  # Default colormap
+```
+
+### Keyboard Shortcuts
+
+| Action | Windows/Linux | MacOS |
+|--------|--------------|-------|
+| Reset Analysis | Ctrl+R | Cmd+R |
+| Export Results | Ctrl+E | Cmd+E |
+| Quick Save | Ctrl+S | Cmd+S |
+
+## Installing DinoSoft
+
+This guide walks you through installing DinoSoft for your needs.
+
+### System Requirements
+
+Prerequisites:
+
+- Python 3.8 or higher
+- 4GB RAM minimum
+- CUDA-compatible GPU recommended
+
+### Installation Methods
+
+#### pip (Recommended)
+
+Set up a virtual environment, or if done simply run `pip`.
+```bash
+python -m venv dinoenv
+source dinoenv/bin/activate  # Linux/Mac
+pip install dinosoft
+```
+
+Available extras:
+```bash
+pip install dinosoft[viz]     # Visualization tools
+pip install dinosoft[ml]      # Machine learning features
+pip install dinosoft[full]    # All optional dependencies
+```
+
+#### conda
+```bash
+conda create -n dinoenv python=3.9
+conda activate dinoenv
+conda install -c paleochannel dinosoft
+```
+
+#### Development
+```bash
+git clone https://github.com/dinosoft/dinosoft.git
+cd dinosoft
+pip install -e ".[dev]"
+```
+
+Common Issues:
+
+- **ImportError**: Check Python version compatibility
+- **GPU not detected**: Verify CUDA installation
+- **Memory Error**: Increase available RAM
+
+## Using DinoSoft
+
+This guide shows you how to perform common tasks with DinoSoft.
+
 ### Basic Usage
 
 ```python
 import dinosoft as ds
 
 def analyze_fossil_record(specimen):
     """Process paleontological data"""
-    # Main analysis function
-    # Loads extinction event database
     extinction_dates = ds.timeline.mass_extinctions
-    # AI-powered diet classification
     diet_analysis = ds.classify_diet(specimen)
-    # Territory size estimation
     territory = ds.calculate_territory(specimen.size)
     
     return ds.Species(
@@ -142,7 +213,7 @@ def analyze_fossil_record(specimen):
 
 ### Advanced Examples
 
-**Species Analysis**
+#### Species Analysis
 ```python
 # Load and analyze a specimen
 specimen = ds.load_specimen(
@@ -151,7 +222,7 @@ specimen = ds.load_specimen(
 )
 ```
 
-**Population Modeling**
+#### Population Modeling
 ```python
 # Create a population model
 pop = ds.Population(
@@ -161,7 +232,7 @@ pop = ds.Population(
 )
 ```
 
-**Visualization**
+#### Visualization
 ```python
 import matplotlib.pyplot as plt
 
@@ -187,44 +258,27 @@ except ds.errors.SpecimenError as e:
     logger.error(f"Specimen error: {e}")
 ```
 
-## Configuration Reference
-
-Create `dinosoft.yml` in your project root:
-
-```yaml
-analysis:
-  settings:
-    precision: high     # Analysis precision
-    units: metric      # Measurement units
-  visualization:
-    style: journal     # Publication style
-    colormap: viridis  # Default colormap
-```
-
-### Keyboard Shortcuts
-
-| Action | Windows/Linux | MacOS |
-|--------|--------------|-------|
-| Reset Analysis | Ctrl+R | Cmd+R |
-| Export Results | Ctrl+E | Cmd+E |
-| Quick Save | Ctrl+S | Cmd+S |
+## Roadmap and Support
 
-## API Status
+### API Status
 
-- DONE: Core Analysis Engine
-- DONE: Data Import/Export (Supports all major museum formats)
-- WIP: Neural Networks*
-- WIP: Web Interface
+- DONE Core Analysis Engine
+- DONE Data Import/Export :material-information-outline:{title="Supports all major museum formats"}
+- WIP Neural Networks[^1]
+- WIP Web Interface
 
-*Coming in version 2.0
+[^1]: Coming in version 2.0
 
-**Version History**
+Version History:
 
 - 1.2.0: Added machine learning models
 - 1.1.0: Improved analysis speed
 - 1.0.0: Initial release
 
-**Need Support?**
-- [Join Discord](https://discord.gg/dinosoft)
-- [GitHub](https://github.com/dinosoft/dinosoft)
-- [API Docs](api/)
+### Support
+
+Need Support?
+
+- :fontawesome-brands-discord: [Join Discord](https://discord.gg/dinosoft){ .tooltip title="Get real-time help" }
+- :fontawesome-brands-github: [GitHub](https://github.com/dinosoft/dinosoft)
+- :fontawesome-solid-book: [API Docs](../reference/index.md)