Warning, /acts/docs/SNIPPETS.md is written in an unsupported language. File is not indexed.
0001 # Documentation Snippet Pattern
0002
0003 ## Overview
0004
0005 ACTS documentation uses **inline code snippets** from working example files rather than duplicating code in markdown files. This ensures documentation examples remain up-to-date and compilable.
0006
0007 ## How It Works
0008
0009 ### 1. Define Snippets in Source Files
0010
0011 Wrap code sections with special comment markers:
0012
0013 **C++ Example** (`docs/examples/logging.cpp`):
0014
0015 ```cpp
0016 //! [Member Logger Pattern]
0017 struct MyClass {
0018 std::unique_ptr<const Acts::Logger> m_logger;
0019 const Acts::Logger &logger() const { return *m_logger; }
0020
0021 MyClass(std::unique_ptr<const Acts::Logger> logger)
0022 : m_logger(std::move(logger)) {}
0023 };
0024 //! [Member Logger Pattern]
0025 ```
0026
0027 **Python Example** (`docs/examples/test_odd.py`):
0028
0029 ```python
0030 def test_basic():
0031 #! [Basic ODD construction]
0032 import acts.root
0033 from acts.examples.odd import getOpenDataDetectorDirectory
0034
0035 odd_dir = getOpenDataDetectorDirectory()
0036 detector = getOpenDataDetector(materialDecorator=materialDecorator)
0037 #! [Basic ODD construction]
0038 ```
0039
0040 ### 2. Reference Snippets in Documentation
0041
0042 Use Doxygen's `@snippet` command in markdown files:
0043
0044 **In `docs/groups/logging.md`:**
0045
0046 ```markdown
0047 ### Member Logger Pattern
0048
0049 Use this pattern when a class needs persistent logging throughout its lifetime.
0050
0051 @snippet{trimleft} examples/logging.cpp Member Logger Pattern
0052 ```
0053
0054 **Options:**
0055
0056 - `@snippet{trimleft}` - Removes leading whitespace (recommended)
0057 - `@snippet` - Preserves original indentation
0058
0059 ### 3. Build the Example Code
0060
0061 Ensure snippet files are compiled to catch errors:
0062
0063 **In `docs/CMakeLists.txt`:**
0064
0065 ```cmake
0066 # Build examples to validate snippets
0067 add_library(docs-examples SHARED)
0068 target_sources(docs-examples PRIVATE examples/logging.cpp)
0069 target_link_libraries(docs-examples PRIVATE Acts::Core)
0070 ```
0071
0072 For Python snippets, use pytest or similar to validate syntax. This is already set up.
0073
0074 ## Benefits
0075
0076 - **Always Current**: Documentation reflects actual working code
0077 - **Compile-Time Verification**: Broken examples cause build failures
0078 - **Single Source of Truth**: No duplication between docs and examples
0079 - **Easy Maintenance**: Update code once, documentation updates automatically
0080
0081 ## Best Practices
0082
0083 1. **Keep snippets focused**: Extract only the relevant portion of code
0084 2. **Use descriptive names**: Snippet names should clearly indicate their purpose
0085 3. **Test the examples**: Build/run example files to ensure they work
0086 4. **Minimize context**: Snippets should be understandable without reading the entire file
0087 5. **Document around snippets**: Add explanatory text before/after the `@snippet` command
0088
0089 ## File Naming Conventions
0090
0091 - Example source files: `docs/examples/*.cpp`, `docs/examples/*.py`
0092 - Documentation files: `docs/groups/*.md`
0093 - Snippet names: Use spaces, describe the pattern/concept (e.g., "Member Logger Pattern")
0094
0095 ## Referencing Snippets in Header Files
0096
0097 When documenting classes or components in header files (`.hpp`), you can also use snippets to provide executable examples. This is especially useful for replacing inline code blocks in namespace or class documentation.
0098
0099 **Example in a header file** (`Core/include/Acts/Definitions/Units.hpp`):
0100
0101 ```cpp
0102 /// @namespace Acts::UnitConstants
0103 /// @brief Constants and helper literals for physical units.
0104 ///
0105 /// Here is how to use unit constants:
0106 ///
0107 /// @snippet{trimleft} examples/units.cpp Using Unit Constants
0108 ///
0109 /// Or use user-defined literals for more concise code:
0110 ///
0111 /// @snippet{trimleft} examples/units.cpp Using Unit Literals
0112 namespace UnitConstants {
0113 // ... constants ...
0114 }
0115 ```
0116
0117 **Benefits for header file documentation:**
0118 - Examples are verified at compile time
0119 - Reduces clutter in header files
0120 - Makes documentation easier to maintain
0121 - Ensures examples use actual working code
