Closed rdzman closed 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?
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.
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?
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 ...
:ref:`foo.ClassA`
:ref:`foo.pkgFoo.ClassB`
or :ref:`foo.+pkgFoo.ClassB`
:ref:`bar.ClassC`
:ref:`bar.pkgBar.ClassD`
or :ref:`bar.+pkgBar.ClassD`
... 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.
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.
I agree. That would be ideal.
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
target.+package.ClassFoo
After
package.ClassFoo
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
Thank you @joeced!
This is a huge step forward. Your effort here is very much appreciated.
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.
Released version 0.19.0 now!
Yay! Congrats! This is a huge step forward.
And I would vote for making matlab_short_links
default to True
in some future version.
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 ...
and I want to use
autoclass
to generate documentation, how can I get them to show up asmyClassA
andmyPkg.myClassB
?If I use the following in
conf.py
...... I can get the
myPkg.myClassB
by using.. automodule:: +myPkg
, but then I can't figure out how to get.. autoclass
to work formyClassA
.