-
Notifications
You must be signed in to change notification settings - Fork 8
Description
Building the docs with Sphinx produces some errors/warnings. These don't prevent the docs being built successfully, as long as fail_on_warning is not set to true in .readthedocs.yaml. However, Read The Docs recommends having fail_on_warning set to true, to avoid broken references. It would be nice to fix these warnings so we get proper alerts of any new warnings that could cause issues.
Abbreviated Sphinx output:
[...]
[AutoAPI] Adding AutoAPI TOCTree [autoapi/index] to index.rst
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:56: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:83: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:89: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:105: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:105: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:121: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:127: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:143: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:572: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:599: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:605: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:621: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:621: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:637: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:643: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:659: ERROR: Unknown interpreted text role "paramref". [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/occlusions/index.rst:31: ERROR: Unexpected indentation. [docutils]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/responsibility/index.rst:69: ERROR: Unexpected indentation. [docutils]
looking for now-outdated files... none found
[...]
writing output... [100%] index
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/box/index.rst:198: WARNING: 'any' reference target not found: TreeError [ref.any]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:316: WARNING: undefined label: 'types_typedecorator' [ref.ref]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:343: WARNING: undefined label: 'types_typedecorator' [ref.ref]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:516: WARNING: undefined label: 'types_typedecorator' [ref.ref]
/Users/k2474365/Documents/Projects/Chockler/ReX/rex-repo/docs/autoapi/rex_xai/database/index.rst:543: WARNING: undefined label: 'types_typedecorator' [ref.ref]
[...]
-
The error
Unknown interpreted text role "paramref"is as mentioned here and can be fixed by enabling the paramlinks extension, but we don't otherwise need this extension enabled so I'm not sure that's the best solution. Importing sqlalchemy and referencing all used functions/classes as e.g.sqlalchemy.create_enginedidn't fix the issue for me. -
WARNING: undefined label: 'types_typedecorator'also seems to come from sqlalchemy -
WARNING: 'any' reference target not found: TreeError- presumably this is a reference to an error type defined within anytree? -
ERROR: Unexpected indentation.- having inspected these, I think they should be fixed by converted the docstrings to Google-style.
Apart from 4, I'm not sure how to fix these yet, so I'm leaving this as a note for future reference.