Merge pull request RobotLocomotion#9588 from m-chaturvedi/common_anno…

…tation

Add documentation to pydrake.common.* modules

bindings/pydrake/common/BUILD.bazel

@@ -28,6 +28,7 @@ PACKAGE_INFO = get_pybind_package_info("//bindings")
 # `libdrake.so`.
 drake_pybind_library(
     name = "_init_py",
+    cc_deps = ["//bindings/pydrake:documentation_pybind"],
     cc_so_name = "_module_py",
     cc_srcs = ["module_py.cc"],
     package_info = PACKAGE_INFO,

bindings/pydrake/common/module_py.cc

@@ -2,6 +2,7 @@
 #include "pybind11/pybind11.h"
 #include "pybind11/stl.h"
 
+#include "drake/bindings/pydrake/documentation_pybind.h"
 #include "drake/bindings/pydrake/pydrake_pybind.h"
 #include "drake/common/constants.h"
 #include "drake/common/drake_assert.h"
@@ -26,12 +27,17 @@ void trigger_an_assertion_failure() {
 PYBIND11_MODULE(_module_py, m) {
   m.doc() = "Bindings for //common:common";
 
+  auto& doc = pydrake_doc.drake;
   m.attr("_HAVE_SPDLOG") = logging::kHaveSpdlog;
 
-  py::enum_<drake::RandomDistribution>(m, "RandomDistribution")
-    .value("kUniform", drake::RandomDistribution::kUniform)
-    .value("kGaussian", drake::RandomDistribution::kGaussian)
-    .value("kExponential", drake::RandomDistribution::kExponential);
+  py::enum_<drake::RandomDistribution>(m, "RandomDistribution",
+    doc.RandomDistribution.doc)
+    .value("kUniform", drake::RandomDistribution::kUniform,
+    doc.RandomDistribution.kUniform.doc)
+    .value("kGaussian", drake::RandomDistribution::kGaussian,
+    doc.RandomDistribution.kGaussian.doc)
+    .value("kExponential", drake::RandomDistribution::kExponential,
+    doc.RandomDistribution.kExponential.doc);
 
 // Turn DRAKE_ASSERT and DRAKE_DEMAND exceptions into native SystemExit.
   // Admittedly, it's unusual for a python library like pydrake to raise
@@ -48,29 +54,33 @@ PYBIND11_MODULE(_module_py, m) {
   m.def("AddResourceSearchPath", &AddResourceSearchPath,
         "Adds a path in which to search for resource files. "
         "The path refers to the relative path within the Drake repository, ",
-        py::arg("search_path"));
+        py::arg("search_path"),
+        doc.AddResourceSearchPath.doc);
   // Convenient wrapper to get the list of resource search paths.
   m.def("GetResourceSearchPaths", &GetResourceSearchPaths,
         "Gets a copy of the list of paths set programmatically in which "
-        "resource files are searched.");
+        "resource files are searched.",
+        doc.GetResourceSearchPaths.doc);
   // Convenient wrapper for querying FindResource(resource_path).
   m.def("FindResourceOrThrow", &FindResourceOrThrow,
         "Attempts to locate a Drake resource named by the given path string. "
         "The path refers to the relative path within the Drake repository, "
         "e.g., drake/examples/pendulum/Pendulum.urdf. Raises an exception "
         "if the resource was not found.",
-        py::arg("resource_path"));
+        py::arg("resource_path"),
+        doc.FindResourceOrThrow.doc);
   m.def("temp_directory", &temp_directory,
         "Returns a directory location suitable for temporary files that is "
         "the value of the environment variable TEST_TMPDIR if defined or "
         "otherwise ${TMPDIR:-/tmp}/robotlocomotion_drake_XXXXXX where each X "
         "is replaced by a character from the portable filename character set. "
-        "Any trailing / will be stripped from the output.");
+        "Any trailing / will be stripped from the output.",
+        doc.temp_directory.doc);
   // Returns the fully-qualified path to the root of the `drake` source tree.
   #pragma GCC diagnostic push
   #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
   m.def("GetDrakePath", &GetDrakePath,
-        "Get Drake path");
+        "Get Drake path", doc.GetDrakePath.doc);
   #pragma GCC diagnostic pop  // pop -Wdeprecated-declarations
   // These are meant to be called internally by pydrake; not by users.
   m.def("set_assertion_failure_to_throw_exception",