From abbeab83f19d68f96bf45539c84f205da493afab Mon Sep 17 00:00:00 2001
From: Xi Xu <i@xi-xu.me>
Date: Fri, 6 Jun 2025 17:39:15 +0800
Subject: [PATCH] Update documentation with indexing and references

Added the ':no-index:' directive to CLI, core, and exceptions API documentation to exclude them from indexing. Updated examples documentation to use Sphinx references for better navigation and added section anchors for improved structure.
---
 docs/api/cli.md        |  1 +
 docs/api/core.md       |  1 +
 docs/api/exceptions.md |  1 +
 docs/examples.md       | 32 ++++++++++++++++++++++++--------
 4 files changed, 27 insertions(+), 8 deletions(-)

diff --git a/docs/api/cli.md b/docs/api/cli.md
index d978a3d..16de7b4 100644
--- a/docs/api/cli.md
+++ b/docs/api/cli.md
@@ -7,6 +7,7 @@ The command-line interface module provides comprehensive functionality for the t
    :members:
    :undoc-members:
    :show-inheritance:
+   :no-index:
 ```
 
 ## Overview
diff --git a/docs/api/core.md b/docs/api/core.md
index 911bee1..368bac7 100644
--- a/docs/api/core.md
+++ b/docs/api/core.md
@@ -7,6 +7,7 @@ The core module provides the main functionality for working with tzst archives,
    :members:
    :undoc-members:
    :show-inheritance:
+   :no-index:
 ```
 
 ## TzstArchive Class
diff --git a/docs/api/exceptions.md b/docs/api/exceptions.md
index 71551cf..9b2d07e 100644
--- a/docs/api/exceptions.md
+++ b/docs/api/exceptions.md
@@ -7,6 +7,7 @@ Custom exception classes used by tzst for comprehensive error handling and debug
    :members:
    :undoc-members:
    :show-inheritance:
+   :no-index:
 ```
 
 ## Overview
diff --git a/docs/examples.md b/docs/examples.md
index 3396f52..9b0259f 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -4,14 +4,16 @@ This section provides comprehensive examples of using tzst for various scenarios
 
 ## Table of Contents
 
-- [Basic Operations](#basic-operations)
-- [Advanced Archive Creation](#advanced-archive-creation)
-- [Flexible Extraction](#flexible-extraction)
-- [Security and Filtering](#security-and-filtering)
-- [Performance Optimization](#performance-optimization)
-- [Error Handling](#error-handling)
-- [Real-World Scenarios](#real-world-scenarios)
-- [Integration Examples](#integration-examples)
+- {ref}`basic-operations`
+- {ref}`advanced-archive-creation`
+- {ref}`flexible-extraction`
+- {ref}`security-and-filtering`
+- {ref}`performance-optimization`
+- {ref}`error-handling`
+- {ref}`real-world-scenarios`
+- {ref}`integration-examples`
+
+(basic-operations)=
 
 ## Basic Operations
 
@@ -125,6 +127,8 @@ tzst t backup.tzst
 tzst l huge-archive.tzst --streaming
 ```
 
+(advanced-archive-creation)=
+
 ## Advanced Archive Creation
 
 ### Working with the TzstArchive Class
@@ -198,6 +202,8 @@ create_archive("important-data.tzst", ["critical/"], use_temp_file=True)
 create_archive("temp-data.tzst", ["temp/"], use_temp_file=False)
 ```
 
+(flexible-extraction)=
+
 ## Flexible Extraction
 
 ### Extracting with Different Structures
@@ -272,6 +278,8 @@ def extract_large_files_only(archive_path, output_dir, min_size_mb=10):
 extract_large_files_only("mixed-content.tzst", "large-files/", min_size_mb=5)
 ```
 
+(security-and-filtering)=
+
 ## Security and Filtering
 
 ### Safe Extraction Practices
@@ -365,6 +373,8 @@ extract_archive("archive.tzst", "output/",
                 interactive_callback=custom_conflict_handler)
 ```
 
+(performance-optimization)=
+
 ## Performance Optimization
 
 ### Streaming for Large Archives
@@ -465,6 +475,8 @@ file_groups = {
 create_archive_batch(file_groups)
 ```
 
+(error-handling)=
+
 ## Error Handling
 
 ### Comprehensive Error Handling
@@ -571,6 +583,8 @@ def validate_and_repair_archive(archive_path):
 validate_and_repair_archive("potentially-corrupted.tzst")
 ```
 
+(real-world-scenarios)=
+
 ## Real-World Scenarios
 
 ### Automated Backup System
@@ -882,6 +896,8 @@ if __name__ == "__main__":
     )
 ```
 
+(integration-examples)=
+
 ## Integration Examples
 
 ### Django Management Command