search

sphinx-contrib / matlabdomain

A Sphinx extension for documenting Matlab code
Other
64 stars 45 forks source link

Check if auto-linking feature works with classes in folders with the same name. #235

Closed joeced closed 7 months ago

joeced commented 7 months ago 
          I haven't looked at all of the details, but I think this is likely incompatible with some auto-linking. For example, there are places where it is assumed that an `entities_table` entry is a `MatObject` and specifically that it has a `ref_role()` method.

Some examples ...

https://github.com/sphinx-contrib/matlabdomain/blob/2fc26b2022f67374a4c7caa291e6f955dc4b2009/sphinxcontrib/mat_documenters.py#L237

https://github.com/sphinx-contrib/matlabdomain/blob/2fc26b2022f67374a4c7caa291e6f955dc4b2009/sphinxcontrib/mat_documenters.py#L274

https://github.com/sphinx-contrib/matlabdomain/blob/2fc26b2022f67374a4c7caa291e6f955dc4b2009/sphinxcontrib/mat_documenters.py#L313

Originally posted by @rdzman in https://github.com/sphinx-contrib/matlabdomain/issues/230#issuecomment-1863525251

itsmoosh commented 7 months ago

I encountered a different problem stemming from the same assumption. The documentation for an existing project broke as of the 0.21.2 release because of this assumption.

This change to make use of short names: https://github.com/sphinx-contrib/matlabdomain/blob/a86ae6452a582aa1f51a68e1609ffa124086e3e7/sphinxcontrib/mat_types.py#L296-L307 breaks the build for projects that use matlab_auto_link = 'all' and have a top-level directory named the same as one nested in another directory.

For example, my project uses misc/ to contain project logos, one of which is displayed in the README. This file must be copied over into the docs, so docs/misc/ also exists, so that the relative file path from the README is able to be reused. When the short_names block linked above is reached, the docs/misc "module" is confused with the misc "module" and a dict is inserted for the entities_table entry instead of a MatModule object.

I'll work on drafting a PR that solves my problem. It might also enable the block to work with class folders.

joeced commented 7 months ago

Hi, thanks for the report.

I'm working on this in https://github.com/sphinx-contrib/matlabdomain/pull/237. @rdzman I hope this fixes it.

Perhaps you could try to install it directly from the branch with

pip install git+https://github.com/sphinx-contrib/matlabdomain.git@fix-autolinking-in-module-class-same-names
joeced commented 7 months ago

Closed with #237