Add configuration to not show args in class signature (#193)

* New option: class_signature

If the option `class_signature` is `True`, iit will display the
constructor argument list in the class signature. The default value is
`False` as this is closer to MATLAB.

* Reorder configuration values by importance.

* Fixed wording

* Wording

* Fix failing test.

Author: joeced

README.rst

@@ -58,32 +58,17 @@ Additional Configuration
 
 ``matlab_src_dir``
    In order for the Sphinx MATLAB domain to auto-document MATLAB source code,
-   set the config value of ``matlab_src_dir`` to the absolute path. Currently
-   only one MATLAB path can be specified, but all subfolders in that tree will
-   be searched.
-
-``matlab_src_encoding``
-   The encoding of the MATLAB files. By default, the files will be read as utf-8
-   and parsing errors will be replaced using ? chars. *Added in Version 0.9.0*.
-
-``matlab_keep_package_prefix``
-   Determines if the MATLAB package prefix ``+`` is displayed in the
-   generated documentation.  Default is ``False``.  When ``False``, packages are
-   still referred to in ReST using ``+pakage.+subpkg.func`` but the output
-   will be ``pakage.other.func()``. *Added in Version
-   0.11.0*.
-
-``matlab_show_property_default_value``
-   Show property default values in the rendered document. Default is ``False``,
-   which is what MathWorks does in their documentation. *Added in Version
-   0.16.0*.
+   set the config value of ``matlab_src_dir`` to an absolute path. Currently
+   only one MATLAB path can be specified, but that folder and all the subfolders
+   in that tree will be searched.
 
 ``matlab_short_links``
    Shorten all class, package and functions to the minimum length. This assumes
    that everything is in the path as we would expect it in MATLAB. This will
    resemble a more MATLAB-like presentation. If it is ``True`` is forces
-   ``matlab_keep_package_prefix = False``. Further, it allows for much shorter and cleaner references.
-   Example, given a path to a class like ``target.subfolder.ClassFoo``.
+   ``matlab_keep_package_prefix = False``. Further, it allows for much shorter
+   and cleaner references. Example, given a path to a class like
+   ``target.subfolder.ClassFoo``.
 
    * With ``False``::
 
@@ -95,9 +80,6 @@ Additional Configuration
 
    Default is ``False``. *Added in Version 0.19.0*.
 
-If you want the closest to MATLAB documentation style, use ``matlab_short_links
-= True`` in your ``conf.py`` file.
-
 ``matlab_auto_link``
    Automatically convert the names of known entities (e.g. classes, functions,
    properties, methods) to links Valid values are ``"basic"``
@@ -119,6 +101,30 @@ If you want the closest to MATLAB documentation style, use ``matlab_short_links
 
    Default is ``None``. *Added in Version 0.20.0*.
 
+``matlab_show_property_default_value``
+   Show property default values in the rendered document. Default is ``False``,
+   which is what MathWorks does in their documentation. *Added in Version
+   0.16.0*.
+
+``matlab_class_signature``
+   Shows the constructor argument list in the class signature if ``True``.
+   Default is ``False``. *Added in Version 0.20.0*.
+
+``matlab_keep_package_prefix``
+   Determines if the MATLAB package prefix ``+`` is displayed in the generated
+   documentation.  Default is ``False``.  When ``False``, packages are still
+   referred to in ReST using ``+pakage.+subpkg.func`` but the output will be
+   ``pakage.subpkg.func()``. Forced to ``False`` if  ``matlab_short_links`` is
+   ``True``. *Added in Version 0.11.0*.
+
+``matlab_src_encoding``
+   The encoding of the MATLAB files. By default, the files will be read as utf-8
+   and parsing errors will be replaced using ? chars. *Added in Version 0.9.0*.
+
+If you want the closest to MATLAB documentation style, use ``matlab_short_links
+= True`` and ``matlab_auto_link = "basic"`` or ``matlab_auto_link = "all"`` in
+your ``conf.py`` file.
+
 
 Roles and Directives
 --------------------

sphinxcontrib/mat_documenters.py

@@ -913,8 +913,6 @@ def can_document_member(cls, member, membername, isattr, parent):
     def format_args(self):
         if self.object.args:
             return "(" + ", ".join(self.object.args) + ")"
-        else:
-            return None
 
     def document_members(self, all_members=False):
         pass
@@ -973,20 +971,20 @@ def import_object(self):
         return ret
 
     def format_args(self):
-        # for classes, the relevant signature is the "constructor" method,
-        # which has the same name as the class definition
-        initmeth = self.get_attr(self.object, self.object.name, None)
-        # classes without constructor method, default constructor or
-        # constructor written in C?
-        if initmeth is None or not isinstance(initmeth, MatMethod):
+        """Format arguments
+
+        We use the method named the same as the class for arguments, but we only
+        renders the arguments if `matlab_class_signature` is True and the method
+        exist.
+        """
+        ctor = self.get_attr(self.object, self.object.name, None)
+
+        if ctor is None or not isinstance(ctor, MatMethod):
             return None
-        if initmeth.args:
-            if initmeth.args[0] in ("obj", "self"):
-                return "(" + ", ".join(initmeth.args[1:]) + ")"
-            else:
-                return "(" + ", ".join(initmeth.args) + ")"
-        else:
+        if ctor and not self.env.config.matlab_class_signature:
             return None
+        if ctor.args:
+            return "(" + ", ".join(ctor.args) + ")"
 
     def format_signature(self):
         if self.doc_as_attr:
@@ -1277,8 +1275,18 @@ def import_object(self):
         return ret
 
     def format_args(self):
+        """Format argument
+
+        We omit `obj` and `self` from the output if they are the first argument
+        unless it's a class constructor.
+
+        Rendering -> "(arg1, arg2, arg3)"
+
+        """
+        is_ctor = self.object.cls.name == self.object.name
+
         if self.object.args:
-            if self.object.args[0] in ("obj", "self"):
+            if self.object.args[0] in ("obj", "self") and not is_ctor:
                 return "(" + ", ".join(self.object.args[1:]) + ")"
             else:
                 return "(" + ", ".join(self.object.args) + ")"

sphinxcontrib/matlab.py

@@ -864,6 +864,7 @@ def setup(app):
     app.add_config_value("matlab_show_property_default_value", False, "env")
     app.add_config_value("matlab_short_links", False, "env")
     app.add_config_value("matlab_auto_link", None, "env")
+    app.add_config_value("matlab_class_signature", False, "env")
 
     app.registry.add_documenter("mat:module", doc.MatModuleDocumenter)
     app.add_directive_to_domain(

tests/test_autodoc.py

@@ -36,7 +36,7 @@ def test_target(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "target\n\n\n\nclass target.ClassExample(a)\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb\n\na property with default value\n\n\n\nc\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
+        == "target\n\n\n\nclass target.ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb\n\na property with default value\n\n\n\nc\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
     )
     assert (
         property_section.rawsource
@@ -61,7 +61,7 @@ def test_target_show_default_value(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "target\n\n\n\nclass target.ClassExample(a)\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb = 10\n\na property with default value\n\n\n\nc = [10; ... 30]\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
+        == "target\n\n\n\nclass target.ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb = 10\n\na property with default value\n\n\n\nc = [10; ... 30]\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
     )
     assert (
         property_section.rawsource
@@ -135,7 +135,7 @@ def test_classfolder(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "classfolder\n\n\n\nclass target.@ClassFolder.ClassFolder(p)\n\nA class in a folder\n\nProperty Summary\n\n\n\n\n\np\n\na property of a class folder\n\nMethod Summary\n\n\n\n\n\nmethod_inside_classdef(a, b)\n\nMethod inside class definition"
+        == "classfolder\n\n\n\nclass target.@ClassFolder.ClassFolder\n\nA class in a folder\n\nProperty Summary\n\n\n\n\n\np\n\na property of a class folder\n\nMethod Summary\n\n\n\n\n\nmethod_inside_classdef(a, b)\n\nMethod inside class definition"
     )
 
 
@@ -252,7 +252,7 @@ def test_root(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "root\n\n\n\nclass BaseClass(args)\n\nA class in the very root of the directory\n\nBaseClass Methods:\n\nBaseClass - the constructor, whose description extends\n\nto the next line\n\nDoBase - another BaseClass method\n\nSee Also\n\ntarget.ClassExample, baseFunction, ClassExample\n\nConstructor Summary\n\n\n\n\n\nBaseClass(args)\n\nThe constructor\n\nMethod Summary\n\n\n\n\n\nDoBase()\n\nDo the Base thing\n\n\n\nbaseFunction(x)\n\nReturn the base of x\n\nSee Also:\n\ntarget.submodule.ClassMeow\ntarget.package.ClassBar\nClassMeow\npackage.ClassBar"
+        == "root\n\n\n\nclass BaseClass\n\nA class in the very root of the directory\n\nBaseClass Methods:\n\nBaseClass - the constructor, whose description extends\n\nto the next line\n\nDoBase - another BaseClass method\n\nSee Also\n\ntarget.ClassExample, baseFunction, ClassExample\n\nConstructor Summary\n\n\n\n\n\nBaseClass(obj, args)\n\nThe constructor\n\nMethod Summary\n\n\n\n\n\nDoBase()\n\nDo the Base thing\n\n\n\nbaseFunction(x)\n\nReturn the base of x\n\nSee Also:\n\ntarget.submodule.ClassMeow\ntarget.package.ClassBar\nClassMeow\npackage.ClassBar"
     )
 
 
@@ -267,7 +267,7 @@ def test_root_show_default_value(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "root\n\n\n\nclass BaseClass(args)\n\nA class in the very root of the directory\n\nBaseClass Methods:\n\nBaseClass - the constructor, whose description extends\n\nto the next line\n\nDoBase - another BaseClass method\n\nSee Also\n\ntarget.ClassExample, baseFunction, ClassExample\n\nConstructor Summary\n\n\n\n\n\nBaseClass(args)\n\nThe constructor\n\nMethod Summary\n\n\n\n\n\nDoBase()\n\nDo the Base thing\n\n\n\nbaseFunction(x)\n\nReturn the base of x\n\nSee Also:\n\ntarget.submodule.ClassMeow\ntarget.package.ClassBar\nClassMeow\npackage.ClassBar"
+        == "root\n\n\n\nclass BaseClass\n\nA class in the very root of the directory\n\nBaseClass Methods:\n\nBaseClass - the constructor, whose description extends\n\nto the next line\n\nDoBase - another BaseClass method\n\nSee Also\n\ntarget.ClassExample, baseFunction, ClassExample\n\nConstructor Summary\n\n\n\n\n\nBaseClass(obj, args)\n\nThe constructor\n\nMethod Summary\n\n\n\n\n\nDoBase()\n\nDo the Base thing\n\n\n\nbaseFunction(x)\n\nReturn the base of x\n\nSee Also:\n\ntarget.submodule.ClassMeow\ntarget.package.ClassBar\nClassMeow\npackage.ClassBar"
     )
 
 
@@ -297,5 +297,20 @@ def test_root_auto_link_basic(make_app, rootdir):
     )
 
 
+@pytest.mark.skipif(sys.version_info < (3, 6), reason="requires python3.6 or higher")
+def test_root_class_signature(make_app, rootdir):
+    srcdir = rootdir / "roots" / "test_autodoc"
+    confdict = {"matlab_class_signature": True}
+    app = make_app(srcdir=srcdir, confoverrides=confdict)
+    app.builder.build_all()
+
+    content = pickle.loads((app.doctreedir / "index_root.doctree").read_bytes())
+    assert len(content) == 1
+    assert (
+        content[0].astext()
+        == "root\n\n\n\nclass BaseClass(obj, args)\n\nA class in the very root of the directory\n\nBaseClass Methods:\n\nBaseClass - the constructor, whose description extends\n\nto the next line\n\nDoBase - another BaseClass method\n\nSee Also\n\ntarget.ClassExample, baseFunction, ClassExample\n\nConstructor Summary\n\n\n\n\n\nBaseClass(obj, args)\n\nThe constructor\n\nMethod Summary\n\n\n\n\n\nDoBase()\n\nDo the Base thing\n\n\n\nbaseFunction(x)\n\nReturn the base of x\n\nSee Also:\n\ntarget.submodule.ClassMeow\ntarget.package.ClassBar\nClassMeow\npackage.ClassBar"
+    )
+
+
 if __name__ == "__main__":
     pytest.main([__file__])

tests/test_autodoc_short_links.py

@@ -37,7 +37,7 @@ def test_target(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "target\n\n\n\nclass ClassExample(a)\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb\n\na property with default value\n\n\n\nc\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
+        == "target\n\n\n\nclass ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb\n\na property with default value\n\n\n\nc\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
     )
     assert (
         property_section.rawsource
@@ -62,7 +62,7 @@ def test_target_show_default_value(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "target\n\n\n\nclass ClassExample(a)\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb = 10\n\na property with default value\n\n\n\nc = [10; ... 30]\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
+        == "target\n\n\n\nclass ClassExample\n\nBases: handle\n\nExample class\n\nClassExample Properties:\n\na - first property of ClassExample\nb - second property of ClassExample\nc - third property of ClassExample\n\nClassExample Methods:\n\nClassExample - the constructor and a reference to mymethod()\nmymethod - a method in ClassExample\n\nSee also BaseClass, baseFunction, b, unknownEntity, mymethod.\n\nProperty Summary\n\n\n\n\n\na\n\na property\n\n\n\nb = 10\n\na property with default value\n\n\n\nc = [10; ... 30]\n\na property with multiline default value\n\nMethod Summary\n\n\n\n\n\nmymethod(b)\n\nA method in ClassExample\n\nParameters\n\nb – an input to mymethod()"
     )
     assert (
         property_section.rawsource
@@ -137,7 +137,7 @@ def test_classfolder(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "classfolder\n\n\n\nclass ClassFolder(p)\n\nA class in a folder\n\nProperty Summary\n\n\n\n\n\np\n\na property of a class folder\n\nMethod Summary\n\n\n\n\n\nmethod_inside_classdef(a, b)\n\nMethod inside class definition"
+        == "classfolder\n\n\n\nclass ClassFolder\n\nA class in a folder\n\nProperty Summary\n\n\n\n\n\np\n\na property of a class folder\n\nMethod Summary\n\n\n\n\n\nmethod_inside_classdef(a, b)\n\nMethod inside class definition"
     )
 
 
@@ -257,7 +257,7 @@ def test_root(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "root\n\n\n\nclass BaseClass(args)\n\nA class in the very root of the directory\n\nBaseClass Methods:\n\nBaseClass - the constructor, whose description extends\n\nto the next line\n\nDoBase - another BaseClass method\n\nSee Also\n\ntarget.ClassExample, baseFunction, ClassExample\n\nConstructor Summary\n\n\n\n\n\nBaseClass(args)\n\nThe constructor\n\nMethod Summary\n\n\n\n\n\nDoBase()\n\nDo the Base thing\n\n\n\nbaseFunction(x)\n\nReturn the base of x\n\nSee Also:\n\ntarget.submodule.ClassMeow\ntarget.package.ClassBar\nClassMeow\npackage.ClassBar"
+        == "root\n\n\n\nclass BaseClass\n\nA class in the very root of the directory\n\nBaseClass Methods:\n\nBaseClass - the constructor, whose description extends\n\nto the next line\n\nDoBase - another BaseClass method\n\nSee Also\n\ntarget.ClassExample, baseFunction, ClassExample\n\nConstructor Summary\n\n\n\n\n\nBaseClass(obj, args)\n\nThe constructor\n\nMethod Summary\n\n\n\n\n\nDoBase()\n\nDo the Base thing\n\n\n\nbaseFunction(x)\n\nReturn the base of x\n\nSee Also:\n\ntarget.submodule.ClassMeow\ntarget.package.ClassBar\nClassMeow\npackage.ClassBar"
     )
 
 
@@ -272,7 +272,7 @@ def test_root_show_default_value(make_app, rootdir):
     assert len(content) == 1
     assert (
         content[0].astext()
-        == "root\n\n\n\nclass BaseClass(args)\n\nA class in the very root of the directory\n\nBaseClass Methods:\n\nBaseClass - the constructor, whose description extends\n\nto the next line\n\nDoBase - another BaseClass method\n\nSee Also\n\ntarget.ClassExample, baseFunction, ClassExample\n\nConstructor Summary\n\n\n\n\n\nBaseClass(args)\n\nThe constructor\n\nMethod Summary\n\n\n\n\n\nDoBase()\n\nDo the Base thing\n\n\n\nbaseFunction(x)\n\nReturn the base of x\n\nSee Also:\n\ntarget.submodule.ClassMeow\ntarget.package.ClassBar\nClassMeow\npackage.ClassBar"
+        == "root\n\n\n\nclass BaseClass\n\nA class in the very root of the directory\n\nBaseClass Methods:\n\nBaseClass - the constructor, whose description extends\n\nto the next line\n\nDoBase - another BaseClass method\n\nSee Also\n\ntarget.ClassExample, baseFunction, ClassExample\n\nConstructor Summary\n\n\n\n\n\nBaseClass(obj, args)\n\nThe constructor\n\nMethod Summary\n\n\n\n\n\nDoBase()\n\nDo the Base thing\n\n\n\nbaseFunction(x)\n\nReturn the base of x\n\nSee Also:\n\ntarget.submodule.ClassMeow\ntarget.package.ClassBar\nClassMeow\npackage.ClassBar"
     )