search

sphinx-contrib / matlabdomain

A Sphinx extension for documenting Matlab code
http://sphinxcontrib-matlabdomain.readthedocs.io/
Other
69 stars 45 forks source link

mixing classes in packages and main namespace #166

Closed rdzman closed 1 year ago

rdzman commented 1 year ago

I'm trying to do something that I think should be straightforward, but I haven't found a way to make it work yet.

If I have ...

/src
 |
 +-- myClassA.m
 |
 +-- +myPkg
       |
       +-- myClassB.m

and I want to use autoclass to generate documentation, how can I get them to show up as myClassA and myPkg.myClassB?

If I use the following in conf.py ...

matlab_src_dir = /src
add_module_names = True
matlab_keep_package_prefix = False

... I can get the myPkg.myClassB by using .. automodule:: +myPkg, but then I can't figure out how to get .. autoclass to work for myClassA.

rdzman commented 1 year ago

The README states ...

If no module is specified then Sphinx will assume that the object is a built-in.

But if I try to use .. autofunction:: or .. autoclass:: without first using ..automodule:: or .. currentmodule::, it throws a fatal error:

Exception occurred:
  File "/Users/ray/bin/sphinx-6b/lib/python3.10/site-packages/sphinxcontrib/mat_documenters.py", line 550, in generate
    self.directive.warn(
AttributeError: 'DocumenterBridge' object has no attribute 'warn'
The full traceback has been saved in /var/folders/jg/9wj7zjkd0xs65bhpww3gphvh0000gn/T/sphinx-err-8i_9d1xg.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

So is it not possible to have a function/class that has no corresponding module/package?

Or can you have it display the module/package for some functions/classes and not for others?

joeced commented 1 year ago

Thanks for the report. Evidently this will not work at the moment. This is one of the short comings of being built upon the Python autodoc feature. The automodule assumes a real name, if you give it a . for current directory it will fail with the error you saw.

This should definitely also be fixed.

rdzman commented 1 year ago

Ok, thanks. I was afraid it was me. 😉

As a workaround, I don't suppose there is an option to reverse the add_module_names config value for an individual .. autoclass:: directive, is there?

rdzman commented 1 year ago

While we are talking about fixing this, let me lay out some of my thoughts.

The following seem to me to be completely reasonable expectations:

For example, suppose we want to auto-document projects foo and bar, with the source arranged as follows, where the projects would be installed by adding /src/foo and /src/bar to the MATLAB path.

/src/
  |
  +-- foo/
  |    |
  |    +-- ClassA.m
  |    |
  |    +-- +pkgFoo/
  |           |
  |           +-- ClassB.m
  |
  +-- bar/
       |
       +-- ClassC.m
       |
       +-- +pkgBar/
              |
              +-- ClassD.m

I think we would want to reference the 4 classes above, respectively, as ...

... and have them rendered, respectively, as ...

If I'm not mistaken, we are actually pretty close. Am I right in thinking that currently it always includes foo and bar (which are not part of any MATLAB namespace)? So they are rendered as ...

If so, all we need is the ability to trim off the first part of the name when rendering. That would solve the original problem as well.

joeced commented 1 year ago

I had the dream that we could even trim the references you describe even further. Given that if you want to run a class, function or script in MATLAB it has to be on the path. Thus, the notion of a "module" does not make much sense.

If I could have the time for it, I would rather have these

:ref:`ClassA`
:ref:`pkgFoo.ClassB`
:ref:`ClassC`
:ref:`pkgBar.ClassD`

However, since so much of the code is based on Python nomenclature and types, I found it difficult to trim it down.

rdzman commented 1 year ago

I agree. That would be ideal.

joeced commented 1 year ago

I started working on getting short links and rendering in #171 Stay tuned :)

The goal is to render all functions, classes, packages as MATLAB.

Before

After

joeced commented 1 year ago

Pre-release version 0.19.0rc1 is now released. It includes the new configuration option matlab_short_links, which enables MATLAB names, rather than dotted paths.

pip install sphinxcontrib-matlabdomain==0.19.0rc1

rdzman commented 1 year ago

Thank you @joeced!

This is a huge step forward. Your effort here is very much appreciated.

joeced commented 1 year ago

I'm trying to get some major users of the extension to test it out. Let's see how that goes. On Monday I'll try it on my work projects.

Edit: Opened issues at:

Waiting some days for reaction.

Tried it at work - it's big improvement in the visual appearance.

joeced commented 1 year ago

Released version 0.19.0 now!

rdzman commented 1 year ago

Yay! Congrats! This is a huge step forward.

And I would vote for making matlab_short_links default to True in some future version.