Merge pull request #100 from psardin001/pr/documentation

Fix and expand DocClassMethod() usage to add it to relevant functions

Author: florent-lamiraux

doc/configure.py

@@ -116,7 +116,13 @@ def _xmlDirFromPkgConfig(pkg):
 
 nsToPackage = {
     "hpp::core": _xmlDirFromPkgConfig("hpp-core"),
+    "hpp::core::path": _xmlDirFromPkgConfig("hpp-core"),
     "hpp::constraints": _xmlDirFromPkgConfig("hpp-constraints"),
+    "hpp::constraints::solver": _xmlDirFromPkgConfig("hpp-constraints"),
+    "hpp::pinocchio": _xmlDirFromPkgConfig("hpp-pinocchio"),
+    "hpp::manipulation": _xmlDirFromPkgConfig("hpp-manipulation"),
+    "hpp::manipulation::graph": _xmlDirFromPkgConfig("hpp-manipulation"),
+    "hpp::manipulation::pathPlanner": _xmlDirFromPkgConfig("hpp-manipulation"),
 }
 
 
@@ -142,7 +148,7 @@ def make_doc_string(brief, detailled):
 
 
 def make_args_string(args):
-    return "(" + ",".join(['arg("' + a + '")' for a in args]) + ")"
+    return "(" + ",".join(['boost::python::arg("' + a + '")' for a in args]) + ")"
 
 
 def substitute(istr, ostr):

doc/doxygen_xml_parser.py

@@ -16,14 +16,18 @@ def _getCompound(self, kind, name):
 
     def classDoc(self, name):
         el = self._getCompound("class", name)
-        return ClassDoc(path.join(self.directory, el.get("refid") + ".xml"))
+        return ClassDoc(
+            path.join(self.directory, el.get("refid") + ".xml"), self.directory
+        )
 
 
 class ClassDoc:
-    def __init__(self, filename):
+    def __init__(self, filename, directory=None):
         self.tree = etree.parse(filename)
         self.compound = self.tree.find("./compounddef")
         self.classname = self.compound.find("compoundname").text.strip()
+        self.directory = directory if directory else path.dirname(filename)
+        self._group_cache = {}
 
     @staticmethod
     def _getDoc(el):
@@ -33,30 +37,91 @@ def _getDoc(el):
         detailed = d.text.strip() if d.text else ""
         return brief, detailed
 
+    def _getMemberFromGroup(self, memberDefKind, name):
+        """Look for memberdef in a group file via member refid."""
+        members = self.compound.xpath(
+            "sectiondef/member[@kind='" + memberDefKind + "' and name='" + name + "']"
+        )
+        if not members:
+            return None
+        member = members[0]
+        refid = member.get("refid")
+        if not refid:
+            return None
+        group_id = refid.rsplit("_1", 1)[0]
+        if group_id not in self._group_cache:
+            group_file = path.join(self.directory, group_id + ".xml")
+            if not path.isfile(group_file):
+                return None
+            self._group_cache[group_id] = etree.parse(group_file)
+        group_tree = self._group_cache[group_id]
+        memberdefs = group_tree.xpath(
+            "//memberdef[@id='" + refid + "' and @kind='" + memberDefKind + "']"
+        )
+        if memberdefs:
+            return memberdefs[0]
+        return None
+
+    def _getMemberFromInherited(self, memberDefKind, name):
+        """Look for memberdef in base class XML via listofallmembers member refid."""
+        members = self.compound.xpath("listofallmembers/member[name='" + name + "']")
+        if not members:
+            return None
+        member = members[0]
+        refid = member.get("refid")
+        if not refid:
+            return None
+        # Extract base class file from refid
+        # e.g., "classhpp_1_1pinocchio_1_1AbstractDevice_1a312..." -> "classhpp_1_1pinocchio_1_1AbstractDevice"
+        parts = refid.rsplit("_1", 1)
+        if len(parts) < 2:
+            return None
+        base_class_id = parts[0]
+        base_class_file = path.join(self.directory, base_class_id + ".xml")
+        if not path.isfile(base_class_file):
+            return None
+        if base_class_id not in self._group_cache:
+            self._group_cache[base_class_id] = etree.parse(base_class_file)
+        base_tree = self._group_cache[base_class_id]
+        memberdefs = base_tree.xpath(
+            "//memberdef[@id='" + refid + "' and @kind='" + memberDefKind + "']"
+        )
+        if memberdefs:
+            return memberdefs[0]
+        return None
+
     def _getMember(self, sectionKind, memberDefKind, name):
-        # return self.compound.xpath ("sectiondef[@kind='" + sectionKind
-        try:
-            return self.compound.xpath(
-                "sectiondef[re:test(@kind,'"
-                + sectionKind
-                + "')]/memberdef[@kind='"
-                + memberDefKind
-                + "' and name='"
-                + name
-                + "']",
-                namespaces={"re": "http://exslt.org/regular-expressions"},
-            )[0]
-        except IndexError as e:
-            msg = (
-                "Error: Could not find member ("
-                + sectionKind
-                + ") "
-                + name
-                + " of class "
-                + self.classname
-            )
-            print(msg + "\n" + str(e), file=sys.stderr)
-            raise IndexError(msg)
+        # First try to find memberdef directly in class XML
+        results = self.compound.xpath(
+            "sectiondef[re:test(@kind,'"
+            + sectionKind
+            + "')]/memberdef[@kind='"
+            + memberDefKind
+            + "' and name='"
+            + name
+            + "']",
+            namespaces={"re": "http://exslt.org/regular-expressions"},
+        )
+        if results:
+            return results[0]
+        # Fall back to looking in group files (for @ingroup documented classes)
+        memberdef = self._getMemberFromGroup(memberDefKind, name)
+        if memberdef is not None:
+            return memberdef
+        # Fall back to looking in base class files (for inherited methods)
+        memberdef = self._getMemberFromInherited(memberDefKind, name)
+        if memberdef is not None:
+            return memberdef
+        msg = (
+            "Error: Could not find member ("
+            + sectionKind
+            + ") "
+            + name
+            + " of class "
+            + self.classname
+        )
+        print(msg, file=sys.stderr)
+        raise IndexError(msg)
 
     def getClassDoc(self):
         return self._getDoc(self.compound)

src/pyhpp/constraints/by-substitution.cc

@@ -31,7 +31,7 @@
 #include <hpp/constraints/solver/by-substitution.hh>
 #include <pyhpp/constraints/fwd.hh>
 
-// DocNamespace(hpp::constraints)
+// DocNamespace(hpp::constraints::solver)
 
 using namespace boost::python;
 
@@ -54,7 +54,7 @@ void exposeBySubstitution() {
       .value("INFEASIBLE", HierarchicalIterative::INFEASIBLE)
       .value("SUCCESS", HierarchicalIterative::SUCCESS);
 
-  // DocClass(solver::BySubstitution)
+  // DocClass(BySubstitution)
   class_<BySubstitution, bases<HierarchicalIterative> >(
       "BySubstitution", init<LiegroupSpacePtr_t>())
       .def("explicitConstraintSetHasChanged",

src/pyhpp/constraints/explicit.cc

@@ -31,6 +31,8 @@
 #include <hpp/constraints/explicit.hh>
 #include <pinocchio/multibody/fwd.hpp>
 
+// DocNamespace(hpp::constraints)
+
 using namespace boost::python;
 
 namespace pyhpp {
@@ -61,6 +63,7 @@ ExplicitPtr_t createExplicit(const LiegroupSpacePtr_t& configSpace,
 }
 
 void exposeExplicit() {
+  // DocClass(Explicit)
   class_<Explicit, ExplicitPtr_t, boost::noncopyable>("Explicit", no_init)
       .def("create", &createExplicit)
       .staticmethod("create");

src/pyhpp/constraints/generic-transformation.cc

@@ -31,6 +31,8 @@
 #include <hpp/constraints/generic-transformation.hh>
 #include <pyhpp/constraints/fwd.hh>
 
+// DocNamespace(hpp::constraints)
+
 using namespace boost::python;
 
 namespace pyhpp {

src/pyhpp/constraints/implicit.cc

@@ -61,7 +61,7 @@ void exposeImplicit() {
       .def("comparisonType",
            static_cast<const ComparisonTypes_t& (Implicit::*)() const>(
                &Implicit::comparisonType),
-           return_internal_reference<>())
+           return_internal_reference<>(), DocClassMethod(comparisonType))
       .def("comparisonType",
            static_cast<void (Implicit::*)(const ComparisonTypes_t&)>(
                &Implicit::comparisonType))

src/pyhpp/constraints/locked-joint.cc

@@ -25,6 +25,8 @@
 #include <hpp/pinocchio/liegroup-element.hh>
 #include <pyhpp/constraints/fwd.hh>
 
+// DocNamespace(hpp::constraints)
+
 using namespace boost::python;
 
 namespace pyhpp {

src/pyhpp/constraints/relative-com.cc

@@ -32,6 +32,9 @@
 #include <hpp/pinocchio/device.hh>
 #include <pyhpp/core/fwd.hh>
 #include <pyhpp/util.hh>
+
+// DocNamespace(hpp::constraints)
+
 using namespace boost::python;
 
 namespace pyhpp {
@@ -64,9 +67,10 @@ static RelativeComPtr_t create3(const std::string& name,
 }
 
 void exposeRelativeCom() {
+  // DocClass(RelativeCom)
   class_<RelativeCom, RelativeComPtr_t, bases<DifferentiableFunction>,
          boost::noncopyable>("RelativeCom", no_init)
-      .def("create", &create1)
+      .def("create", &create1, DocClassMethod(create))
       .def("create", &create2)
       .def("create", &create3)
       .staticmethod("create");

src/pyhpp/core/config-validation.cc

@@ -69,7 +69,7 @@ void exposeConfigValidation() {
       .PYHPP_DEFINE_METHOD2(ConfigValidations, add, DocClassMethod(add))
       .PYHPP_DEFINE_METHOD2(ConfigValidations, numberConfigValidations,
                             DocClassMethod(numberConfigValidations))
-      .PYHPP_DEFINE_METHOD2(ConfigValidations, clear, DocClassMethod(clear));
+      .def("clear", &ConfigValidations::clear);
 }
 }  // namespace core
 }  // namespace pyhpp

src/pyhpp/core/configuration-shooter.cc

@@ -32,6 +32,8 @@
 #include <pyhpp/core/fwd.hh>
 #include <pyhpp/util.hh>
 
+// DocNamespace(hpp::core)
+
 using namespace boost::python;
 
 namespace pyhpp {
@@ -43,9 +45,10 @@ struct CSWrapper {
 };
 
 void exposeConfigurationShooter() {
+  // DocClass(ConfigurationShooter)
   class_<ConfigurationShooter, ConfigurationShooterPtr_t, boost::noncopyable>(
       "ConfigurationShooter", no_init)
-      .def("shoot", &CSWrapper::shoot);
+      .def("shoot", &CSWrapper::shoot, DocClassMethod(shoot));
 }
 }  // namespace core
 }  // namespace pyhpp