1  # Documentation Testing Annotations
 2  
 3  This file demonstrates how to add testing annotations to documentation code blocks.
 4  
 5  ## Basic Code Block
 6  
 7  Simple code blocks are tested automatically:
 8  
 9  
10  ## Code Block with Expected Output
11  
12  You can specify expected output for validation:
13  
14  
15  ## Code Block with Multiple Julia Versions
16  
17  Test compatibility across Julia versions:
18  
19  
20  ## Code Block with Requirements
21  
22  Specify required packages:
23  
24  
25  ## Code Block with Custom Timeout
26  
27  For long-running examples:
28  
29  
30  ## Skipped Code Block
31  
32  Some code blocks should not be tested (e.g., pseudocode):
33  
34  ```julia
35  # DOCTEST_SKIP
36  # This is just pseudocode to illustrate a concept
37  function my_strategy(data)
38      # ... implementation details
39      return result
40  end
41  ```
42  
43  ## Interactive Examples
44  
45  Code that requires user interaction should be skipped:
46  
47  
48  ## Complex Example with Multiple Annotations
49  
50  
51  ## Example with Output Validation Features
52  
53  This example demonstrates the enhanced output validation:
54  
55  
56  ## Testing Guidelines
57  
58  1. **Use DOCTEST_SKIP** for:
59     - Pseudocode examples
60     - Interactive examples
61     - Examples requiring external services
62     - Examples with non-deterministic output
63  
64  2. **Use DOCTEST_REQUIRES** for:
65     - Examples needing specific packages
66     - Examples requiring optional dependencies
67  
68  3. **Use DOCTEST_OUTPUT** for:
69     - Examples where output validation is important
70     - Examples demonstrating specific results
71  
72  4. **Use DOCTEST_TIMEOUT** for:
73     - Long-running optimization examples
74     - Examples involving data downloads
75     - Complex computations
76  
77  ## Best Practices
78  
79  - Keep code examples simple and focused
80  - Ensure examples are self-contained
81  - Use realistic but minimal data
82  - Avoid examples that depend on external state
83  - Test examples locally before committing