Skip to content

Latest commit

 

History

History
 
 

docs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
_static
_static
 
 
_templates
_templates
 
 
doxygen
doxygen
 
 
README.md
README.md
 
 
apiDocs.rst
apiDocs.rst
 
 
conf.py
conf.py
 
 
contributing_to_usd.rst
contributing_to_usd.rst
 
 
contributors.rst
contributors.rst
 
 
dl_city_set.rst
dl_city_set.rst
 
 
dl_downloads.rst
dl_downloads.rst
 
 
dl_kitchen_set.rst
dl_kitchen_set.rst
 
 
dl_license.rst
dl_license.rst
 
 
dl_usdskel_examples.rst
dl_usdskel_examples.rst
 
 
glossary.rst
glossary.rst
 
 
index.rst
index.rst
 
 
index_body.rst
index_body.rst
 
 
intro.rst
intro.rst
 
 
maxperf.rst
maxperf.rst
 
 
plugins.rst
plugins.rst
 
 
plugins_alembic.rst
plugins_alembic.rst
 
 
plugins_renderman.rst
plugins_renderman.rst
 
 
press_opensource_announce.rst
press_opensource_announce.rst
 
 
press_opensource_release.rst
press_opensource_release.rst
 
 
rolesAndUtils.rst
rolesAndUtils.rst
 
 
spec.rst
spec.rst
 
 
spec_usdpreviewsurface.rst
spec_usdpreviewsurface.rst
 
 
spec_usdz.rst
spec_usdz.rst
 
 
toc.rst
toc.rst
 
 
toolset.rst
toolset.rst
 
 
tut_authoring_variants.rst
tut_authoring_variants.rst
 
 
tut_converting_between_layer_formats.rst
tut_converting_between_layer_formats.rst
 
 
tut_end_to_end.rst
tut_end_to_end.rst
 
 
tut_generating_new_schema.rst
tut_generating_new_schema.rst
 
 
tut_helloworld.rst
tut_helloworld.rst
 
 
tut_helloworld_redux.rst
tut_helloworld_redux.rst
 
 
tut_historical_badge.rst
tut_historical_badge.rst
 
 
tut_houdini_example.rst
tut_houdini_example.rst
 
 
tut_inspect_and_author_props.rst
tut_inspect_and_author_props.rst
 
 
tut_referencing_layers.rst
tut_referencing_layers.rst
 
 
tut_setup_version_badge.rst
tut_setup_version_badge.rst
 
 
tut_simple_shading.rst
tut_simple_shading.rst
 
 
tut_traversing_stage.rst
tut_traversing_stage.rst
 
 
tut_usd_tutorials.rst
tut_usd_tutorials.rst
 
 
tut_usdview_plugin.rst
tut_usdview_plugin.rst
 
 
tut_variants_example_in_katana.rst
tut_variants_example_in_katana.rst
 
 
tut_xforms.rst
tut_xforms.rst
 
 
usdfaq.rst
usdfaq.rst
 
 
wp.rst
wp.rst
 
 
wp_ar2.rst
wp_ar2.rst
 
 
wp_connectable_nodes.rst
wp_connectable_nodes.rst
 
 
wp_coordsys.rst
wp_coordsys.rst
 
 
wp_render_settings.rst
wp_render_settings.rst
 
 
wp_rigid_body_physics.rst
wp_rigid_body_physics.rst
 
 
wp_usdaudio.rst
wp_usdaudio.rst
 
 
wp_usdlux_for_geometry_lights.rst
wp_usdlux_for_geometry_lights.rst
 
 
wp_usdlux_for_renderers.rst
wp_usdlux_for_renderers.rst
 
 
wp_usdpreviewsurface.rst
wp_usdpreviewsurface.rst
 
 
wp_usdshade.rst
wp_usdshade.rst
 
 
wp_usdz.rst
wp_usdz.rst
 
 

README.md

Style and Build Guide for USD Documentation

USD uses Sphinx to generate its user documentation and Doxygen for its API documentation.

Following are introductions to Sphinx, how we use it and style our documentation, and how to build it locally.

Sphinx

The user documentation is specified in restructured text (rst), and makes use of the following Sphinx extensions:

You will need to ensure your installation of sphinx includes these three packages for a documentation build to complete properly.

We have found the following references helpful:

USD Sphinx Style Guide

  • Use ":ref:" to link to section headers in other documents. For example, to link to the "API Schema" entry in glossary.rst, use:

    :ref:`glossary:API Schema` OR
:ref:`Custom Link Text <glossary:API Schema>`

    For intra-page links, however, you must (and only in this case) use the "trailing underbar" syntax:

    `Custom Link Text <glossary:API Schema>`_

  • Use "doc:" to link to other documents. For example, to link to the "Hello World" tutorial in tut_helloworld.rst, use:

    :doc:`tut_helloworld` OR
:doc:`Custom Link Text <tut_helloworld>`

  • Use the ":usdcpp:" role to link to Doxygen API docs for a specified function or class. This is a custom role created using the doxylink extension for sphinx. For example, to link to the UsdStage API docs, use:

    :usdcpp:`UsdStage` OR
:usdcpp:`Custom Link Text <UsdStage>`

  • Please conform the title and section headers to the following convention required by the ReadTheDocs template to work well with the navigation bar:

    Use the following symbols to create headings H1 - H6:

    1. # with overline
    2. * with overline
    3. =
    5. ^
    6. "

  • The code-block directive takes a parameter to specify syntax highlighting. Commonly-used values are: python , cpp , usd , usda, none . e.g.:

    .. code-block:: none

  • Formatting Quickstart

    • *italics* italics
    • **bold** bold
    • :bi:`bolditalics` bolditalics
    • :mono:`monospace` monospace
    • The rolesAndUtils.rst file defines a number of "roles" (e.g. like :mono:) used in these pages for various kinds of objects, including:
      • :sdfpath: for scene description paths, like </World/anim/chars/Bob>
      • :filename: for files/assets
      • :python: for inline python code
      • :cpp: for inline C++ code that does not indicate an API method/class that can be located in the USD doxygen documentation
      • :code: for inline code that is ambiguous with respect to language and does not link to the USD doxygen documentation

Content Notes

  1. The contributors.rst file references a contributors.html file, which is maintained by Pixar internally, and cannot receive pull requests.

Building Documentation Locally

build_usd.py can be used to build the USD doxygen documentation. We may eventually enable it to build the Sphinx documentation as well, but we currently do not want to introduce the Sphinx (and packages) dependency. Following are instructions for building the complete documentation manually.

Sphinx Setup

If your system already has sphinx installed, you must ensure the installation has the sphinx-rtd-theme, sphinx_panels, and sphinxcontrib-doxylink extension packages installed. You can instead install sphinx locally (instructions for linux and python3) like so:

pip3 install --user sphinx sphinx-rtd-theme sphinx_panels sphinxcontrib-doxylink
    
# Add to .cshrc or equivalent command in your shell's configuration file
# Make sure to run rehash or open a new shell to pick up this change.
setenv PATH $HOME/.local/bin:$PATH
    
# Python also needs to find your local install
setenv PYTHONPATH $HOME/.local:$PYTHONPATH

Pulling in API documentation

To enable links to Doxygen API documentation in the user documentation, set the following environment variables before running sphinx-build:

  • USD_DOXYGEN_TAG_FILE

    This should be set to the path of the .tag file generated by the Doxygen documentation build. Sphinx will read this file to determine the HTML files containing documentation for a given class or function.

    By default, the USD build installs this file to USD_INSTALL_ROOT/docs/USD.tag .

  • USD_DOXYGEN_PREFIX

    This should be set to a URI for the directory containing the Doxygen HTML files. Sphinx will prepend all links to Doxygen HTML files with this prefix.

    By default, the USD build installs these files to USD_INSTALL_ROOT/docs/doxy_html

For example, for a USD build installed in USD_INSTALL_ROOT that is not being served by a web-server:

setenv USD_DOXYGEN_TAG_FILE USD_INSTALL_ROOT/docs/USD.tag
setenv USD_DOXYGEN_PREFIX file://USD_INSTALL_ROOT/docs/doxy_html

If these env vars are not set, the user documentation will still build but Sphinx will issue some warnings, and links to API documentation in the user documentation will not appear.

Building User Documentation with Sphinx

To build the user documentation to /tmp/usddocs, you must be in the directory containing this README and the rst source files, and then:

sphinx-build . /tmp/usddocs

Sphinx tracks changed files, so subsequent builds will be faster than the first.