Add more advanced cmake macro features to documentation (#685)

* Update cmake.md

Add advance CMake usage for `PODIO_GENERATE_DATAMODEL`

* Incorporate suggested changes

doc/cmake.md

@@ -43,3 +43,28 @@ PODIO_ADD_SIO_IO_BLOCKS(newdm "${headers}" "${sources}")
 ```
 
 For a complete example, please have a look at [EDM4hep](https://github.com/key4hep/EDM4hep/blob/main/edm4hep/CMakeLists.txt)
+
+## More advanced data model generation
+PODIO provides additional options within the `PODIO_GENERATE_DATAMODEL` macro that allow developers to fine-tune how data models are generated and compiled:
+
+  1. `UPSTREAM_EDM` - use an existing EDM as an upstream dependency. This is useful when your data model extends or builds on top of another one, such as using EDM4hep in [EDM4eic](https://github.com/eic/EDM4eic/blob/7a627488cde0bc4e1863d3fd6bd3396fd30c7296/CMakeLists.txt#L44-L48).
+  2. `DEPENDS` - tells CMake that some files used to build the data model are not generated during the current build but are still required for compilation and should trigger a rebuild in case of changes, like in [EDM4hep](https://github.com/key4hep/EDM4hep/blob/ac83112d66f7aa3b9d4eb5859c19b987feab3ce5/edm4hep/CMakeLists.txt#L6-L8)
+  3. `VERSION` - specifies the version of the datamodel (it is separate from the schema version). This will be injected into the metadata that is stored in files.
+  4. `OUTPUT_FOLDER` - the folder in which the output files should be placed. Defaults to `${CMAKE_CURRENT_SOURCE_DIR}` if not set.
+  5. `IO_BACKEND_HANDLERS` - the I/O backend handlers that should be generated. The list is passed directly to podio_class_generator.py and validated there. Default is `ROOT`
+
+## Example usage of Advanced options
+
+```cmake
+# Generate the C++ code from the YAML definition with an upstream EDM, dependencies, version, output folder, and I/O handlers
+PODIO_GENERATE_DATAMODEL(newdm newdm.yaml headers sources
+    UPSTREAM_EDM "EDM4hep:edm4hep"
+    DEPENDS "extra_header.h;more_extras.h"
+    VERSION "1.0"
+    OUTPUT_FOLDER ${CMAKE_BINARY_DIR}/generated_sources
+    IO_BACKEND_HANDLERS "ROOT;SIO"
+)
+```
+Another example can be found [here](https://github.com/AIDASoft/podio/blob/64e87e153e8217375a167123d3567a765935333a/tests/schema_evolution/CMakeLists.tx).
+
+You can explore all available options [here](https://github.com/AIDASoft/podio/blob/cf147a00e00bfbedb2f66330b837679c0c81f6b2/cmake/podioMacros.cmake#L110-L135).