Use glossary terms for environment variables references in the docs (AcademySoftwareFoundation#1442)

* Use glossary terms for environment variables references in the docs
* Add documentation for livereload

Signed-off-by: Jean-Christophe Morin <[email protected]>
Signed-off-by: Michele Spina <[email protected]>

Author: JeanChristopheMorinPerso

docs/Makefile

@@ -21,6 +21,7 @@ help:
 	@echo "  htmlstrict to make standalone HTML files and fails if any warnings or errors are produced"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
+	@echo "  livehtml   to make standalone HTML files served by a web server that will automatically reload and rebuild when a file changes"
 	@echo "  pickle     to make pickle files"
 	@echo "  json       to make JSON files"
 	@echo "  htmlhelp   to make HTML files and a HTML help project"
@@ -73,6 +74,10 @@ singlehtml:
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
+.PHONY: livehtml
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
 .PHONY: pickle
 pickle:
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle

docs/tutorials/architecture.md

@@ -109,7 +109,7 @@ A range in time.  Encodes the start time and the duration, meaning that end_time
 
 OpenTimelineIO includes several adapters for reading and writing from other file formats. The `otio.adapters` module has convenience functions that will auto-detect which adapter to use, or you can specify the one you want.
 
-Adapters can be added to the system (outside of the distribution) via JSON files that can be placed on the `OTIO_PLUGIN_MANIFEST_PATH` environment variable to be made available to OTIO.
+Adapters can be added to the system (outside of the distribution) via JSON files that can be placed on the {term}`OTIO_PLUGIN_MANIFEST_PATH` environment variable to be made available to OTIO.
 
 Most common usage only cares about:
 - `timeline = otio.adapters.read_from_file(filepath)`
@@ -127,7 +127,7 @@ For more information, see [How To Write An OpenTimelineIO Adapter](write-an-adap
 
 Media linkers run on the otio file after an adapter calls `.read_from_file()` or `.read_from_string()`.  They are intended to replace media references that exist after the adapter runs (which depending on the adapter are likely to be `MissingReference`) with ones that point to valid files in the local system.  Since media linkers are plugins, they can use proprietary knowledge or context and do not need to be part of OTIO itself.
 
-You may also specify a media linker to be run after the adapter, either via the `media_linker_name` argument to `.read_from_file()` or `.read_from_string()` or via the `OTIO_DEFAULT_MEDIA_LINKER` environment variable.  You can also turn the media linker off completely by setting the `media_linker_name` argument to `otio.media_linker.MediaLinkingPolicy.DoNotLinkMedia`.
+You may also specify a media linker to be run after the adapter, either via the `media_linker_name` argument to `.read_from_file()` or `.read_from_string()` or via the {term}`OTIO_DEFAULT_MEDIA_LINKER` environment variable.  You can also turn the media linker off completely by setting the `media_linker_name` argument to `otio.media_linker.MediaLinkingPolicy.DoNotLinkMedia`.
 
 For more information about writing media linkers, see [How To Write An OpenTimelineIO Media Linker](write-a-media-linker).
 

docs/tutorials/otio-env-variables.md

@@ -5,16 +5,39 @@ various aspects of OTIO.
 
 ## Plugin Configuration
 
-These variables must be set _before_ the OpenTimelineIO python library is imported.  They only impact the python library.  The C++ library has no environment variables.
+These variables must be set _before_ the OpenTimelineIO python library is imported.  They only impact the python library. The C++ library has no environment variables.
 
-- `OTIO_PLUGIN_MANIFEST_PATH`: a ":" separated string with paths to .manifest.json files that contain OTIO plugin manifests.  See: [Tutorial on how to write an adapter plugin](write-an-adapter).
-- `OTIO_DEFAULT_MEDIA_LINKER`: the name of the default media linker to use after reading a file, if "" then no media linker is automatically invoked.
-- `OTIO_DISABLE_PKG_RESOURCE_PLUGINS`: By default, OTIO will use the pkg_resource entry_points mechanism to discover plugins that have been installed into the current python environment.  pkg_resources, however, can be slow in certain cases, so for users who wish to disable this behavior, this variable can be set to 1.
-- `OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL`: if no downgrade arguments are passed to `write_to_file`/`write_to_string`, use the downgrade manifest specified by the family/label combination in the variable.  Variable is of the form FAMILY:LABEL.  Only one tuple of FAMILY:LABEL may be specified.
+```{glossary}
+
+OTIO_PLUGIN_MANIFEST_PATH
+    A colon (`:`) on POSIX system (or a semicolon (`;`) on Windows) separated string with paths
+    to `.manifest.json` files that contain OTIO plugin manifests.
+    See the [tutorial on how to write an adapter plugin](write-an-adapter.md) for additional details.
+
+OTIO_DEFAULT_MEDIA_LINKER
+   The name of the default media linker to use after reading a file, if `""` then no
+   media linker is automatically invoked.
+
+OTIO_DISABLE_PKG_RESOURCE_PLUGINS
+   By default, OTIO will use the `pkg_resource` entry_points mechanism to discover plugins
+   that have been installed into the current python environment. `pkg_resources`, however, can
+   be slow in certain cases, so for users who wish to disable this behavior, this variable can be set to 1.
+
+OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL
+   If no downgrade arguments are passed to `write_to_file`/`write_to_string`, use the downgrade manifest
+   specified by the family/label combination in the variable. Variable is of the form `FAMILY:LABEL`.
+   Only one tuple of `FAMILY:LABEL` may be specified.
+```
 
 ## Unit tests
 
 These variables only impact unit tests.
 
-- `OTIO_DISABLE_SHELLOUT_TESTS`: When running the unit tests, skip the console tests that run the otiocat program and check output through the shell.  This is desirable in environments where running the commandline tests is not meaningful or problematic.  Does not disable the tests that run through python calling mechanisms.
-- `OTIO_DISABLE_SERIALIZED_SCHEMA_TEST`: Skip the unit tests that generate documentation and compare the current state of the schema against the stored one. Useful if the documentation is not available from the test directory.
+```{glossary}
+
+OTIO_DISABLE_SHELLOUT_TESTS
+   When running the unit tests, skip the console tests that run the otiocat program and check output through the shell. This is desirable in environments where running the commandline tests is not meaningful or problematic. Does not disable the tests that run through python calling mechanisms.
+
+OTIO_DISABLE_SERIALIZED_SCHEMA_TEST
+   Skip the unit tests that generate documentation and compare the current state of the schema against the stored one. Useful if the documentation is not available from the test directory.
+```

docs/tutorials/versioning-schemas.md

@@ -164,7 +164,7 @@ sc->to_json_file("/var/tmp/simpleclass.otio", &err, &downgrade_manifest);
 
 In python, an additional level of indirection is provided, "FAMILY", which is intended to allow developers to define their own sets of target versions for their plugin schemas.  For example, a studio might have a family named "MYFAMILY" under which they organize labels for their internal releases of their own plugins.
 
-These can be defined in a plugin manifest, which is a `.plugin_manifest.json` file found on the environment variable `${OTIO_PLUGIN_MANIFEST_PATH}`.
+These can be defined in a plugin manifest, which is a `.plugin_manifest.json` file found on the environment variable {term}`OTIO_PLUGIN_MANIFEST_PATH`.
 
 For example:
 
@@ -204,19 +204,19 @@ See the [versioning module](../api/python/opentimelineio.versioning.rst) for mor
 If you are using multiple pieces of software built with mismatched versions of OTIO, you may need to configure the newer one(s) to write out OTIO in an older format without recompiling or modifying the software.
 
 You can accomplish this in two ways:
-- The `OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL` environment variable can specify a family and version.
+- The {term}`OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL` environment variable can specify a family and version.
 - The `otioconvert` utility program can downgrade an OTIO file to an older version.
 
 ### OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL Environment Variable
 
-If your software uses OTIO's Python adapter system, then you can set the `OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL` environment variable with a `FAMILY:VERSION` value.
+If your software uses OTIO's Python adapter system, then you can set the {term}`OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL` environment variable with a `FAMILY:VERSION` value.
 For example, in a *nix shell: `env OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL=OTIO_CORE:0.14.0 my_program`
 
 The `OTIO_CORE` family is pre-populated with the core OTIO schema versions for previous OTIO releases, for example `0.14.0`. If you have custom schema that needs to be downgraded as well, you will need to specify your own family and version mapping, as described above.
 
 ### Downgrading with otioconvert
 
-If your software uses OTIO's C++ API, then it does not look for the `OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL` environment variable, but you can convert an OTIO file after it has been created with the `otioconvert` utility.
+If your software uses OTIO's C++ API, then it does not look for the {term}`OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL` environment variable, but you can convert an OTIO file after it has been created with the `otioconvert` utility.
 
 You can either use a family like this:
 ```

docs/tutorials/write-a-hookscript.md

@@ -45,7 +45,8 @@ To create a new OTIO hook script, you need to create a file myhooks.py. Then add
 
 The ``hook_scripts`` section will register the plugin with the system, and the ``hooks`` section will attach the scripts to hooks.
 
-Then you need to add this manifest to your `$OTIO_PLUGIN_MANIFEST_PATH` environment variable (which is separated with `:` for POSIX or `;` for Windows).  You may also define media linkers and adapters via the same manifest.
+Then you need to add this manifest to your {term}`OTIO_PLUGIN_MANIFEST_PATH` environment variable.
+You may also define media linkers and adapters via the same manifest.
 
 ## Running a Hook Script
 

docs/tutorials/write-a-media-linker.md

@@ -33,9 +33,9 @@ To create a new OTIO Adapter, you need to create a file mymedialinker.py. Then a
         }
 ```
           
-Then you need to add this manifest to your `$OTIO_PLUGIN_MANIFEST_PATH` environment variable (which is separated with `:` for POSIX or `;` for Windows).
+Then you need to add this manifest to your {term}`OTIO_PLUGIN_MANIFEST_PATH` environment variable.
 
-Finally, to specify this linker as the default media linker, set `OTIO_DEFAULT_MEDIA_LINKER` to the name of the media linker:
+Finally, to specify this linker as the default media linker, set {term}`OTIO_DEFAULT_MEDIA_LINKER` to the name of the media linker:
 
 ```bash
     export OTIO_DEFAULT_MEDIA_LINKER="awesome_studios_media_linker"

docs/tutorials/write-a-schemadef.md

@@ -84,8 +84,8 @@ Then you must add it to a plugin manifest:
 
 The same plugin manifest may also include adapters and media linkers, if desired.
 
-Then you need to add this manifest to your `$OTIO_PLUGIN_MANIFEST_PATH` environment
-variable (which is separated with `:` for POSIX or `;` for Windows).
+Then you need to add this manifest to your {term}`OTIO_PLUGIN_MANIFEST_PATH` environment
+variable.
 
 ## Using the New Schema in Your Code
 

docs/tutorials/write-an-adapter.md

@@ -95,7 +95,7 @@ And a `plugin_manifest.json` like:
 
 ### Custom Adapters
 
-Alternately, if you are creating a site specific adapter that you do _not_ intend to share with the community, you can create your `myadapter.py` file anywhere.  In this case, you must create a `mysite.plugin_manifest.json` (with an entry like the below example that points at `myadapter.py`) and then put the path to your `mysite.plugin_manifest.json` on your `$OTIO_PLUGIN_MANIFEST_PATH` environment variable (which is separated with `:` for POSIX or `;` for Windows).
+Alternately, if you are creating a site specific adapter that you do _not_ intend to share with the community, you can create your `myadapter.py` file anywhere.  In this case, you must create a `mysite.plugin_manifest.json` (with an entry like the below example that points at `myadapter.py`) and then put the path to your `mysite.plugin_manifest.json` on your {term}`OTIO_PLUGIN_MANIFEST_PATH` environment variable.
 
 For example, to register `myadapter.py` that supports files with a `.myext` file extension:
 ```json

src/py-opentimelineio/opentimelineio/plugins/manifest.py

@@ -220,7 +220,7 @@ def load_manifest():
 
     The order of loading (and precedence) is:
 
-       1. Manifests specified via the ``OTIO_PLUGIN_MANIFEST_PATH`` variable
+       1. Manifests specified via the :term:`OTIO_PLUGIN_MANIFEST_PATH` variable
        2. Entrypoint based plugin manifests
        3. Builtin plugin manifest
        4. Contrib plugin manifest