Overview

Welcome to the Zootools Pro Developer and reference Documentation. Below you will find detailed technical information about Zootools Core API useful for developers and engineers.

What is Zootools Core

The Zootools Core consists of a set of systems for managing the zootools environment

  • A Descriptor API which handles external resource management, configuration.

  • An extendable CLI for running commands to managing code packages and environments.

  • Environment resolver API for package discovery, management and introspection.

Accessing Zootools Core API

As with all APIs, the Zootools Core API is a combination of public interface and internal logic. We refactor and evolve the code on a regular basis and this sometimes changes internal structure of the code. We recommend only accessing Core via the methods documented in this API reference. These form the official Zootools Core API and we do our best to ensure backwards compatibility.

As a general rule access to the API should be only done via the public interface ‘api.py’ module. This is to provide a cleaner interface and making refactoring easier.

# Recommended API Access
from zoo.core import api
cfg = api.currentConfig()

Building documentation

Zoo Tools allows for generating a single static html page for all of Zoo tools including custom packages.

Before building the documentation you’ll need to install the following:

sphinx
sphinx_rtd_theme
sphinxcontrib-youtube
sphinx-tabs

You can install these libraries using pip, zoo tools docs should be compatible with the latest version.:

pip install  sphinx sphinx_rtd_theme sphinxcontrib-youtube sphinx-tabs

When running any of the below commands you should be using a shell ie. bash, cmd, powershell.

Pre-generating all module api docs

The first time you setup documentation for your package instead of creating all the .rst files manually from scratch you can use sphinx autodoc.

To generate rst files for one or multiple packages:

zootoolsRoot/install/core/bin/zoo_cmd generateDocs --packages myPackageA myPackageB --apiDocs

To generate rst files into a temp folder to avoid clashing with existing custom formatted files use the flag “–apiDocsOutputName test”:

zootoolsRoot/install/core/bin/zoo_cmd generateDocs --packages myPackage --apiDocs --apiDocsOutputName test

To generate rst files for all packages for production use:

zootoolsRoot/install/core/bin/zoo_cmd generateDocs --packages * --apiDocs

Building Html documentation

Once you’ve setup your packages and generated the rst files(if need be) you just run the below:

zootoolsRoot/install/core/bin/zoo_cmd generateDocs --packages * --build --launch

Setting up a package for documentation

To setup documentation for a package you first need to tell zootools where in your package your docs are located.

First open your zoo_package.json and add the documentation entry like the example below. Note you should change the paths to match your package.

Example zoo_package.json entry for specifying custom documentation.

"documentation":
{
    "sourceFolder": "{self}/docs/source",
    "masterDoc": "index.rst",
    "sourceCodeFolder": "{self}/zoo",
    "configScript": "{self}/docs/startupScript.py"
}

Explanation of documentation variables

sourceFolder

The folder path within the package which contains all .rst files.

masterDoc

The base name of the master rst file for the package. ie. index.rst

sourceCodeFolder

The path to the source code ie. {self}/zoo

configScript

The sphinx conf.py which will update or override our config

That’s it now you can follow the instructions for building the documentation see Pre-generating all module api docs.

Mocking third party libraries for documentation

There comes a time when you need to import third party modules which the documentation generator process will not have access too ie. maya, blender etc. This is where per package “configScript” package variable comes into play, this script is run after our internal zoo sphinx config is run this means you have the ability to override our config using standard sphinx conf syntax, Please see official Sphinx Documentation. We do provide a simple mock object for you to use for your modules, this module can be access via the globals

# my custom config script

sys.modules.update((mod_name, MockExt()) for mod_name in {"maya.cmds", "maya"}

We’ve already mocked all Qt modules you shouldn’t need to do these. If you include zoo_maya when generating documentation then all maya modules we also be mocked already for you.