Refactor code samples

docs/src/SUMMARY.md

@@ -3,7 +3,7 @@
 
 ----------------------
 
-- [Introduction](./pages/index.md)
+- [Introduction](./index.md)
     - [Motivation](./pages/introduction/motivation.md) 
     - [Guide Structure](./pages/introduction/structure.md)
     - [Building the guide locally](./pages/introduction/docs.md)

docs/src/index.md

@@ -10,7 +10,7 @@ For more information what makes this guide unique, see the [motivation](./pages/
 This guide was officially introduced at [Siggraph 2023 - Houdini Hive](https://www.sidefx.com/houdini-hive/siggraph-2023/#usd). Special thanks to SideFX for hosting me and throwing such a cool Houdini lounge and presentation line up!
 ```
 
-{{#include contributors.md}}
+{{#include pages/contributors.md}}
 
 ## License 
 This guide is licensed under the **Apache License 2.0**. For more information as to how this affects copyright and distribution see our [license](https://github.com/LucaScheller/VFX-UsdSurvivalGuide/blob/main/LICENSE) page.

docs/src/pages/core/api.md

@@ -36,7 +36,7 @@ Individual components of Usd are loaded via a [plugin based system](./plugins/ov
 Here is a simple comparison:
 ~~~admonish info title=""
 ```python
-{{#include ../../../code/core/elements.py:apiHighVsLowLevel}}
+{{#include ../../../../code/core/elements.py:apiHighVsLowLevel}}
 ```
 ~~~
 

docs/src/pages/core/composition/arcs.md

@@ -65,15 +65,15 @@ In our [Composition Strength Ordering (LIVRPS)](./livrps.md#compositionArcSublay
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcSublayer}}
+{{#include ../../../../../code/core/composition.py:compositionArcSublayer}}
 ```
 ~~~
 
 When working in Houdini, we can't directly sublayer onto the root layer as with native USD, due to Houdini's layer caching mechanism, that makes node based stage editing possible. Layering on the active layer works as usual though.
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcSublayerHoudini}}
+{{#include ../../../../../code/core/composition.py:compositionArcSublayerHoudini}}
 ```
 ~~~
 
@@ -99,7 +99,7 @@ Inherits, like specializes, don't have a object representation, they directly ed
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcInherit}}
+{{#include ../../../../../code/core/composition.py:compositionArcInherit}}
 ```
 ~~~
 
@@ -170,7 +170,7 @@ def Xform "car" (
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcVariant}}
+{{#include ../../../../../code/core/composition.py:compositionArcVariant}}
 ```
 ~~~
 
@@ -179,15 +179,15 @@ def Xform "car" (
 When editing variants, we can also move layer content into a (nested) variant very easily via the `Sdf.CopySpec` command. This is a very powerful feature!
 
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcVariantCopySpec}}
+{{#include ../../../../../code/core/composition.py:compositionArcVariantCopySpec}}
 ```
 ~~~
 
 Here is how we can created nested variant sets via the high level and low level API. As you can see it is quite a bit easier with the low level API.
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcVariantNested}}
+{{#include ../../../../../code/core/composition.py:compositionArcVariantNested}}
 ```
 ~~~
 
@@ -200,15 +200,15 @@ In our [Composition Strength Ordering (LIVRPS)](./livrps.md#compositionArcRefere
 The `Sdf.Reference` class creates a read-only reference description object:
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcReferenceClass}}
+{{#include ../../../../../code/core/composition.py:compositionArcReferenceClass}}
 ```
 ~~~
 
 #### References File <a name="compositionArcReferenceExternal"></a>
 Here is how we add external references (references that load data from other files):
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcReferenceExternal}}
+{{#include ../../../../../code/core/composition.py:compositionArcReferenceExternal}}
 ```
 ~~~
 
@@ -217,7 +217,7 @@ Here is how we add external references (references that load data from other fil
 Here is how we add internal references (references that load data from another part of the hierarchy) :
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcReferenceInternal}}
+{{#include ../../../../../code/core/composition.py:compositionArcReferenceInternal}}
 ```
 ~~~
 
@@ -229,14 +229,14 @@ In our [Composition Strength Ordering (LIVRPS)](./livrps.md#compositionArcPayloa
 The `Sdf.Payload` class creates a read-only payload description object:
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcPayloadClass}}
+{{#include ../../../../../code/core/composition.py:compositionArcPayloadClass}}
 ```
 ~~~
 
 Here is how we add payloads. Payloads always load data from other files:
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcPayload}}
+{{#include ../../../../../code/core/composition.py:compositionArcPayload}}
 ```
 ~~~
 
@@ -249,6 +249,6 @@ Specializes, like inherits, don't have a object representation, they directly ed
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcSpecialize}}
+{{#include ../../../../../code/core/composition.py:compositionArcSpecialize}}
 ```
 ~~~

docs/src/pages/core/composition/fundamentals.md

@@ -80,7 +80,7 @@ These are 100% identical in terms of list ordering functionality, the only diffe
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionListEditableOpsBasics}}
+{{#include ../../../../../code/core/composition.py:compositionListEditableOpsBasics}}
 ```
 ~~~
 
@@ -90,7 +90,7 @@ Let's mock how USD does this without layers:
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionListEditableOpsMerging}}
+{{#include ../../../../../code/core/composition.py:compositionListEditableOpsMerging}}
 ```
 ~~~
 
@@ -193,14 +193,14 @@ stage.SetEditTarget(stage.GetEditTargetForLocalLayer(layer))
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionEditTarget}}
+{{#include ../../../../../code/core/composition.py:compositionEditTarget}}
 ```
 ~~~
 
 For convenience, USD also offers a context manager for variants, so that we don't have to revert to the previous edit target once we are done:
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionEditTargetContext}}
+{{#include ../../../../../code/core/composition.py:compositionEditTargetContext}}
 ```
 ~~~

docs/src/pages/core/composition/listeditableops.md

@@ -53,7 +53,7 @@ These are 100% identical in terms of list ordering functionality, the only diffe
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:listEditableOpsLowLevelAPI}}
+{{#include ../../../../../code/core/composition.py:listEditableOpsLowLevelAPI}}
 ```
 ~~~
 
@@ -66,7 +66,7 @@ When working with the high level API, all the function signatures that work on l
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:listEditableOpsHighLevelAPI}}
+{{#include ../../../../../code/core/composition.py:listEditableOpsHighLevelAPI}}
 ```
 ~~~
 
@@ -86,7 +86,7 @@ Let's mock how USD does this (without using `Sdf.Layer`s to keep it simple):
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:listEditableOpsMerging}}
+{{#include ../../../../../code/core/composition.py:listEditableOpsMerging}}
 ```
 ~~~
 

docs/src/pages/core/composition/livrps.md

@@ -578,14 +578,14 @@ Here is how it can be setup in Houdini:
 Here is the code for moving variants:
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcVariantMoveHoudini}}
+{{#include ../../../../../code/core/composition.py:compositionArcVariantMoveHoudini}}
 ```
 ~~~
 
 And for copying:
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionArcVariantCopyHoudini}}
+{{#include ../../../../../code/core/composition.py:compositionArcVariantCopyHoudini}}
 ```
 ~~~
 
@@ -775,7 +775,7 @@ In Houdini we can show the implicit prototypes by enabling the "Show Implicit Pr
 Here is how we can check if a prim is inside an instance or inside a prototype:
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:compositionInstanceable}}
+{{#include ../../../../../code/core/composition.py:compositionInstanceable}}
 ```
 ~~~
 

docs/src/pages/core/composition/pcp.md

@@ -70,7 +70,7 @@ These return us all value sources for a prim or attribute.
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:pcpPrimPropertyStack}}
+{{#include ../../../../../code/core/composition.py:pcpPrimPropertyStack}}
 ```
 ~~~
 
@@ -86,7 +86,7 @@ Next let's look at the prim index.
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:pcpPrimIndex}}
+{{#include ../../../../../code/core/composition.py:pcpPrimIndex}}
 ```
 ~~~
 
@@ -226,7 +226,7 @@ These are the sub-filters that can be set. We can only set a single token value
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/composition.py:pcpPrimCompositionQuery}}
+{{#include ../../../../../code/core/composition.py:pcpPrimCompositionQuery}}
 ```
 ~~~
 

docs/src/pages/core/elements/animation.md

@@ -29,7 +29,7 @@ Usd encodes time related data in a very simple format:
 
 Reading and writing is quite straight forward:
 ```python
-{{#include ../../../../code/core/elements.py:animationOverview}}
+{{#include ../../../../../code/core/elements.py:animationOverview}}
 ```
 ~~~
 
@@ -120,7 +120,7 @@ The `Usd.TimeCode` class is a small wrapper class for handling time encoding. Cu
 
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:animationTimeCode}}
+{{#include ../../../../../code/core/elements.py:animationTimeCode}}
 ```
 ~~~
 
@@ -141,7 +141,7 @@ Instead you have to create new ones and re-write the arc/assign the new layer of
 
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:animationLayerOffset}}
+{{#include ../../../../../code/core/elements.py:animationLayerOffset}}
 ```
 ~~~
 
@@ -158,7 +158,7 @@ When writing a large amount of samples, you should use the low level API as it i
 
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:animationWrite}}
+{{#include ../../../../../code/core/elements.py:animationWrite}}
 ```
 ~~~
 
@@ -178,15 +178,15 @@ To read data we recommend using the high level API. That way you can also reques
 ~~~admonish tip
 If you need to check if an attribute is time sampled, run the following:
 ```python
-{{#include ../../../../code/core/elements.py:animationTimeVarying}}
+{{#include ../../../../../code/core/elements.py:animationTimeVarying}}
 ```
 If you know the whole layer is in memory, then running GetNumTimeSamples()
 is fine, as it doesn't have t open any files.
 ~~~
 
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:animationRead}}
+{{#include ../../../../../code/core/elements.py:animationRead}}
 ```
 ~~~
 
@@ -195,7 +195,7 @@ You can also tell a time sample to block a value. Blocking means that the attrib
 
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:animationSpecialValues}}
+{{#include ../../../../../code/core/elements.py:animationSpecialValues}}
 ```
 ~~~
 
@@ -243,7 +243,7 @@ The `startTimeCode` and `endTimeCode` entries give intent hints on what the (use
 
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:animationFPS}}
+{{#include ../../../../../code/core/elements.py:animationFPS}}
 ```
 ~~~
 
@@ -262,7 +262,7 @@ Depending on the delegate, you will likely have to set specific primvars that co
 We can also easily derive velocities/accelerations from position data, if our point count doesn't change:
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:animationMotionVelocityAcceleration}}
+{{#include ../../../../../code/core/elements.py:animationMotionVelocityAcceleration}}
 ```
 ~~~
 
@@ -288,7 +288,7 @@ In Houdini you can find it in the `$HFS/bin`folder, e.g. `/opt/hfs19.5/bin`.
 Here is an excerpt:
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:animationStitchCmdlineTool}}
+{{#include ../../../../../code/core/elements.py:animationStitchCmdlineTool}}
 ```
 ~~~
 
@@ -375,7 +375,7 @@ Technically you can remove all default attributes from the per frame files after
 
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:animationStitchClipsUtils}}
+{{#include ../../../../../code/core/elements.py:animationStitchClipsUtils}}
 ```
 ~~~
 
@@ -386,7 +386,7 @@ Since in production (see the next section), we usually want to put the metadata
 And then create the clip metadata in the cache_layer ourselves:
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:animationStitchClipsAPI}}
+{{#include ../../../../../code/core/elements.py:animationStitchClipsAPI}}
 ```
 ~~~
 

docs/src/pages/core/elements/collection.md

@@ -54,7 +54,7 @@ Here are the UsdUtils.ComputeCollectionIncludesAndExcludes [API docs](https://op
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/elements.py:collectionOverview}}
+{{#include ../../../../../code/core/elements.py:collectionOverview}}
 ```
 ~~~
 
@@ -65,6 +65,6 @@ This is very fast and "sparse" as we don't edit leaf prims, instead we find the
 
 ~~~admonish tip title=""
 ```python
-{{#include ../../../../code/core/elements.py:collectionInvert}}
+{{#include ../../../../../code/core/elements.py:collectionInvert}}
 ```
 ~~~

docs/src/pages/core/elements/data_type.md

@@ -66,7 +66,7 @@ To access the base data classes there are three modules:
 The `Vt.Type` registry also handles all on run-time registered types, so not only data types, but also custom types like `Sdf.Spec`,`SdfReference`, etc. that is registered by plugins.
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:tfTypeRegistry}}
+{{#include ../../../../../code/core/elements.py:tfTypeRegistry}}
 ```
 ~~~
 
@@ -114,6 +114,6 @@ We won't be looking at specific data classes on this page, instead we'll have a
 Let's look at this in practice:
 ~~~admonish info title=""
 ```python
-{{#include ../../../../code/core/elements.py:dataTypeRoleOverview}}
+{{#include ../../../../../code/core/elements.py:dataTypeRoleOverview}}
 ```
 ~~~