[docs] allow building of python docstrings without generating HTML docs

[pmolodo]

Description of Change(s)

For those interested in only the python docstrings, this speeds up the build, and reduces the number of necessary extra dependencies (ie, graphviz / dot are no longer required to build python docstrings).

Doxygen is still needed to generate python docstrings, however, as the xml generation is required.

The interface for build_usd.py is mostly unchanged, except that --build-docs and --build-python-docs are now independent of each other - ie, you can now specify --build-python-docs without --build-docs, which will generate just the python docstrings and no html.

At the cmake level, there are now 3 options:

• PXR_BUILD_DOCUMENTATION
• PXR_BUILD_HTML_DOCUMENTATION (new)
• PXR_BUILD_PYTHON_DOCUMENTATION

Both PXR_BUILD_HTML_DOCUMENTATION and
PXR_BUILD_PYTHON_DOCUMENTATION will only have an effect if PXR_BUILD_DOCUMENTATION set. Setting either of the build_usd.py documentation flags (--build-docs and --build-python-docs) will turn on PXR_BUILD_DOCUMENTATION, as well as their own sub-flag.

Both the build_usd.py and cmake interfaces are backwards compatible, in the sense that non-erroring combinations of flags/options will still continue to have the same result as previously.

NOTE:
This PR is one of several targeting the python docstring generation process. To see all these PRs in a branch, see here.

• I have verified that all unit tests pass with the proposed changes

• I have submitted a signed Contributor License Agreement

[jesschimein]

Filed as internal issue #USD-8570

[dsyu-pixar]

Hi @pmolodo apologies for the slow response to these PRs (and thanks for doing them!). Regarding this PR, I had the following Q:

With this change, in build_usd.py, correct me if I'm wrong, but "context.buildDocs" really now means "build/use Doxygen", whereas it used to mean "build C++ HTML docs". This is fine, but in the Summary message the script produces, we use buildDocs to report whether "Documentation" will be built. So, if I use an arg list to build_usd.py that includes "--python --no-docs --python-docs" we end up reporting "Documentation....On" which seems a tiny bit confusing to me. Would it make more sense to try and use "buildHtmlDocs" in the Summary report (I can make this change on my end when I merge)?

[pmolodo]

@dsyu-pixar - Yes, you're right, I think it would be much clearer to report the value of buildHtmlDocs, and make the message more specific
There's some stylistic choices for how to want to name / group stuff, though, so I'll let you handle that. Thanks!

[pmolodo]

Oops - I accidentally updated this branch with an unnecessary rebase. Didn't want to force more code review for a commit that had already been vetted, so I set it back to it's previous state (a403a99).