Contributor Code of Conduct
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+Examples of unacceptable behaviour by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported by opening an issue or contacting one or more of the project maintainers.
+This Code of Conduct is adapted from the Contributor Covenant, version 1.0.0, available at https://contributor-covenant.org/version/1/0/0/.
+
+
+The generated code should (among other things)
+
+- be efficient,
+- offer an easy to use interface,
+- offer performant I/O.
+
+Having automated code generation has a few advantages:
+
+- Freeing the user from the repetitive task of implementing all the types
+ themselves
+- Freeing the user from having to deal with all the details of how to do things
+ efficiently
+- Making it very easy to roll out improved implementations (or bug fixes) via
+ simply regenerating the code
+
+### The three layers of podio
+To achieve the goals stated above podio favors composition over inheritance and
+uses **plain-old-data (POD)** types wherever possible. To achieve this podio
+employs a layered design, which makes it possible to have an efficient memory
+layout and performant I/O implementation, while still offering an easy to use
+interface
+
+![]()
+
+- The *User Layer* is the top most layer and it **offers the full
+ functionality** and is the **only layer with which users interact directly**.
+ It consists mainly of the collections and lightweight handle classes, i.e.
+ - `XYZCollection`
+ - `XYZ`
+ - `MutableXYZ`
+- The *Object Layer* consists of the `XYZObj` classes, that take care of all
+ resource management and which also enable the relations between different
+ objects.
+- The *POD Layer* at the very bottom is where all the actual data lives in
+ simple `XYZData` POD structs. These are the things that are actually stored
+ in, e.g. root files that are written by podio.
+
+### Basics of generated code - value semantics
+The generated c++ code offers so called *value semantics*. The exact details of
+what this actually means are not very important, the main point **is that you
+can treat all objects as values and you don't have to worry about inefficient
+copies or managing resources:**
+
+```cpp
+auto recos = edm4hep::ReconstructedParticleCollection();
+
+// ... fill, e.g. via
+auto p = recos.create();
+// or via
+auto p2 = edm4hep::ReconstructedParticle();
+recos.push_back(p2);
+
+// Loop over a collection
+for (auto reco : recos) {
+ auto vtx = reco.getStartVertex();
+ // do something with the vertex
+
+ // loop over related tracks
+ for (auto track : reco.getTracks()) {
+ // do something with this track
+ }
+}
+```
+
+This looks very similar to the equivalent python code (if you squint a bit, and ignore the `auto`s, `;` and `{}` ;) )
+
+```python
+recos = edm4hep.ReconstructedParticleCollection()
+
+# ... fill, e.g. via
+p = recos.create()
+# or via
+p2 = edm4hep.ReconstructedParticle()
+recos.push_back(p2)
+
+# Loop over a collection
+for reco in recos:
+ vtx = reco.getStartVertex()
+ # do something with the vertex
+
+ # loop over related tracks
+ for track in reco.getTracks():
+ # do something with the tracks
+```
+
+The python interface is functionally equivalent to the one c++ interface, since
+that is implemented via PyROOT. There are some additions that make the python
+interface more *pythonic*, e.g. `len(recos)` is equivalent to `recos.size()`.
+Nevertheless, the doxygen reference is valid for both interfaces.
+
+### Guessing the interface from the yaml definition
+Since all code is generated, it is usually pretty straight forward to guess how
+the interface will look like just from looking at the definition in the yaml
+file. For EDM4hep the general rule is to get a `Member` variable, a
+`OneToOneRelation`, a `OneToManyRelation` or a `VectorMember` is to **simply
+stick a `get` in front of the name in the yaml file and to capitalize the first
+letter.**, e.g.
+
+```yaml
+Members:
+ - edm4hep::Vector3f momentum // the momentum in [GeV]
+```
+will turn into something like
+```cpp
+const edm4hep::Vector3f& getMomentum() const;
+```
+
+Similar, but in slightly more nuanced rules apply for the methods that are
+generated for setting a value. For `Member` variables and `OneToOneRelation`s
+the general rule is to **stick a `set` in front of the name in the yaml file and
+to capitalize the first letter**, e.g. (continuing from above)
+
+```cpp
+void setMomentum(edm4hep::Vector3f value);
+```
+
+For the `OneToManyRelation`s and `VectorMember`s the rule is to **stick a
+`addTo` in front of the name in the yaml file and to capitalize the first
+letter**, e.g.
+
+```yaml
+OneToManyRelation:
+ - MCParticle daughters // the daughters of this particle
+```
+
+will be generated to
+
+```cpp
+void addToDaughters(MCParticle daughter);
+```
+
+### Why is there a `XYZ` and a `MutableXYX`?
+
+The underlying technical reasons are rather complex, dive quite deepish into c++
+nuances, and definitely far beyond the scope of this tutorial. In short: We need
+two different handle classes in order to control whether users are allowed to
+modify things or not. As one of the main goals of podio generated EDMs is to be
+thread safe the default generated class for each data type allows only for
+immutable read access, i.e. it provides only the `get` methods. Only the
+`Mutable` classes actually have the `set` methods, and can hence be used to
+actually modify objects. The most important implication of this is the
+following: **Everything that you read from file, or that you get from the Gaudi
+TES is immutable.** I.e. there is no way for you to change or update the values
+that you read. The only way to "update" values (or collections) is to actually
+copy the contents and then store the updated values back. Independent copies of
+objects can be obtained with the clone` method.
+
+### Writing function interfaces
+The `Mutable` objects implicitly convert to an instance of a default class.
+Hence, **always use the default classes when specifying function interfaces**
+(obviously this only works if you only need read access in the function). **There
+is no implicit conversion from the default, immutable objects to the `Mutable`
+objects!**
+
+As an example
+```cpp
+void printE(edm4hep::MCParticle particle) {
+ std::cout << particle.getEnergy() << '\n';
+}
+
+void printEMutable(edm4hep::MutableMCParticle particle) {
+ std::cout << particle.getEnergy() << '\n';
+}
+
+int main() {
+ auto mutP = edm4hep::MutableMCParticle();
+ p.setEnergy(3.14);
+
+ printE(mutP); // Works due to implicit conversion
+ printEMutable(mutP); // Obviously also works
+
+ // Now we create an immutable object
+ auto P = edm4hep::MCParticle();
+
+ printE(P); // Obviously works
+ printEMutable(P); // BREAKS: No conversion from default to Mutable
+
+ return 0;
+}
+```
+
+### Subset collections
+Similar to LCIO, podio generated EDMs offer a *subset collection functionality*.
+This allows to create collections of objects, that are actually part of another
+collection, e.g. to simply collect all the muons that are present in a larger
+collection of reconstructed particles:
+
+![]()
+
+To create a subset collection, simply do
+```cpp
+auto muons = edm4hep::ReconstructedParticleCollection();
+muons.setSubsetCollection();
+
+// You can now add objects that are part
+// of another collection to this one via push_back
+muons.push_back(recos[0]);
+```
+
+Reading a subset collection works exactly the same as reading a normal
+collection. This is handled in a transparent way, such that you usually don't
+even realize that you are operating on a subset collection.
+
+## The `podio::Frame` container
+
+The `podio::Frame` is a *generalized event*. It is a container that aggregates
+all relevant data (and some meta data). It also defines an implicit *interval of
+validity* (but that is less relevant for this tutorial). It provides a thread
+safe interface for data access
+- Immutable read access only for collections that are stored inside the a
+ `Frame`
+- All data that is inside a `Frame` is owned by it, and this is also reflected
+ in its interface.
+
+![]()
+
+Here we will just briefly introduce the main functionality, for more details see
+the [documentation in
+podio](https://github.com/AIDASoft/podio/blob/master/doc/frame.md).
+
+### Getting collections from a `Frame`
+Assuming that `event` is a `podio::Frame` in the following code examples,
+getting a collection can be done via (c++)
+
+```cpp
+auto& mcParticles = event.get
![]()
+
+
+## `podio-dump`
+The `podio-dump` utility allows to inspect EDM4hep files from the command line.
+The synopsis looks like this
+
+``` console
+$podio-dump --help
+usage: podio-dump [-h] [-c CATEGORY] [-e ENTRIES] [-d] [--dump-edm DUMP_EDM] [--version] inputfile
+
+Dump contents of a podio file to stdout
+
+positional arguments:
+ inputfile Name of the file to dump content from
+
+options:
+ -h, --help show this help message and exit
+ -c CATEGORY, --category CATEGORY
+ Which Frame category to dump
+ -e ENTRIES, --entries ENTRIES
+ Which entries to print. A single number, comma separated list of numbers or "first:last" for an inclusive range of entries. Defaults to the first entry.
+ -d, --detailed Dump the full contents not just the collection info
+ --dump-edm DUMP_EDM Dump the specified EDM definition from the file in yaml format
+ --version show program's version number and exit
+```
+
+By default it prints how many events are present in the file and also a summary
+of the contents of the first event. This overview consists of the names, data
+types and number of elements of the collections that are stored in this event.
+Using the `--detailed` flag, `podio-dump` will print the complete contents of
+all collections in ASCII format. This can be quite a bit of information. Using
+the `--entries` flag it is possible to choose which events to look at. The
+`--categories` flag is an advanced feature and not necessary for this tutorial.
+
+`podio-dump` will also tell you whether the file that is passed to it is a
+*legacy file* in which case you will need the `ROOTLegacyReader` or the
+`SIOLegacyReader` to read it.
diff --git a/_sources/index.md.txt b/_sources/index.md.txt
new file mode 100644
index 0000000..ace4cbe
--- /dev/null
+++ b/_sources/index.md.txt
@@ -0,0 +1,30 @@
+# Key4hep
+
+
+```{eval-rst}
+.. toctree::
+ :maxdepth: 3
+ :includehidden:
+ :caption: Contents:
+
+ setup-and-getting-started/README.md
+ how-tos/README.md
+ tutorials/README.md
+ developing-key4hep-software/README.md
+ spack-build-instructions-for-librarians/README.md
+ talks-and-presentations/README.md
+ call-for-logos/README.md
+ CONTRIBUTING.md
+
+.. toctree::
+ :maxdepth: 2
+ :includehidden:
+ :caption: External links:
+
+ FCC software 
+
+
.
