Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix errors/warnings in Sphinx docs build #5

Open
liz-is opened this issue Oct 22, 2024 · 0 comments
Open

Fix errors/warnings in Sphinx docs build #5

liz-is opened this issue Oct 22, 2024 · 0 comments

Comments

@liz-is
Copy link
Contributor

liz-is commented Oct 22, 2024

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]
[...]
  1. 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_engine didn't fix the issue for me.

  2. WARNING: undefined label: 'types_typedecorator' also seems to come from sqlalchemy

  3. WARNING: 'any' reference target not found: TreeError - presumably this is a reference to an error type defined within anytree?

  4. 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant