diff --git a/.ci/pytorch/cpp_doc_push_script.sh b/.ci/pytorch/cpp_doc_push_script.sh index 6e417bf8bbe9..f085fa78bebe 100755 --- a/.ci/pytorch/cpp_doc_push_script.sh +++ b/.ci/pytorch/cpp_doc_push_script.sh @@ -58,7 +58,7 @@ time python tools/setup_helpers/generate_code.py \ # Build the docs pushd docs/cpp -time make VERBOSE=1 html -j +time make VERBOSE=1 html popd popd diff --git a/.github/workflows/_docs.yml b/.github/workflows/_docs.yml index aba3fa3dceec..77d8482af438 100644 --- a/.github/workflows/_docs.yml +++ b/.github/workflows/_docs.yml @@ -67,7 +67,7 @@ jobs: # an OOM issue when running the job, so this upgrades the runner from 4xlarge # to the next available tier of 12xlarge. So much memory just to generate cpp # doc - runner: ${{ inputs.runner_prefix }}linux.12xlarge + runner: ${{ inputs.runner_prefix }}linux.12xlarge.memory # TODO: Nightly cpp docs take longer and longer to finish (more than 3h now) # Let's try to figure out how this can be improved timeout-minutes: 360 diff --git a/docs/cpp/source/conf.py b/docs/cpp/source/conf.py index 3318ce764f64..10d854c21db4 100644 --- a/docs/cpp/source/conf.py +++ b/docs/cpp/source/conf.py @@ -40,7 +40,34 @@ extensions = [ "sphinx.ext.intersphinx", ] + (["breathe", "exhale"] if run_doxygen else []) -intersphinx_mapping = {"pytorch": ("https://pytorch.org/docs/main", None)} +intersphinx_mapping = {"pytorch": ("https://docs.pytorch.org/docs/main", None)} + +# Configure Sphinx warnings and error handling +suppress_warnings = [ + "ref.citation", + "ref.footnote", + "ref.doc", + "toc.excluded", + "toc.not_readable", + "misc.highlighting_failure", +] + +# Configure Breathe +breathe_show_define_initializer = True +breathe_show_enumvalue_initializer = True +breathe_default_members = ("members", "undoc-members") + + +# Fix for Python 3.10+ compatibility with exhale 2.3.0 +# MutableMapping was moved from collections to collections.abc in Python 3.10 +try: + import collections + from collections.abc import MutableMapping + + if not hasattr(collections, "MutableMapping"): + collections.MutableMapping = MutableMapping +except ImportError: + pass # Setup absolute paths for communicating with breathe / exhale where # items are expected / should be trimmed by. @@ -101,6 +128,21 @@ exhale_args = { Welcome to the developer reference for the PyTorch C++ API. """ ), + ############################################################################ + # Duplicate handling and error management. # + ############################################################################ + # Note: Using Doxyfile instead of stdin configuration + # "exhaleDoxygenStdin" is not compatible with "exhaleUseDoxyfile" + # Handle unresolved references more gracefully + "unabridgedOrphanKinds": { + "function", + "define", + "enum", + "enumvalue", + "typedef", + "variable", + }, + "fullToctreeMaxDepth": 2, } # Tell sphinx what the primary language being documented is.