GNOME.org
 

[glom] Python Glom module: Improved the docstrings, using reStructuredText

commit 79c817255eeae93d99320aeb30e190c9b22a89dc
Author: Murray Cumming <murrayc murrayc com>
Date:   Mon Apr 26 16:25:28 2010 +0200

    Python Glom module: Improved the docstrings, using reStructuredText
    
    * glom/python_embed/python_module/py_glom_module.cc: Use more
        reStructureText (or as much as sphinx allows us to use in a docstring).
        It's looking quite good.

 ChangeLog                                         |   26 +++++---
 glom/python_embed/python_module/py_glom_module.cc |   74 ++++++++++++---------
 2 files changed, 59 insertions(+), 41 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 7e1d2da..0ede5fc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,10 +1,18 @@
+2010-04-26  Murray Cumming  <murrayc murrayc com>
+
+	Python Glom module: Improved the docstrings, using reStructuredText
+
+	* glom/python_embed/python_module/py_glom_module.cc: Use more
+    reStructureText (or as much as sphinx allows us to use in a docstring).
+    It's looking quite good.
+
 2010-04-25  Murray Cumming  <murrayc murrayc com>
 
 	Simplify test_selfhosting_new_empty.
-	
+
 	* glom/frame_glom.cc: Move setup_connection_pool_from_document() to:
 	* glom/libglom/connectionpool.[h|cc]: Added setup_from_document().
-	* tests/test_selfhosting_new_empty/test_selfhosting_new_empty.cc: Use the 
+	* tests/test_selfhosting_new_empty/test_selfhosting_new_empty.cc: Use the
 	new function here, removing code to explicitly set the backend.
 
 2010-04-23  Murray Cumming  <murrayc murrayc com>
@@ -13,23 +21,23 @@
 
 	* glom/Makefile_tests.am: Added the tests.
 	* glom/libglom/test_document.cc: Renamed to example_document_load.cc.
-	* tests/test_document_load/test_document_load.cc: Added this new test to 
+	* tests/test_document_load/test_document_load.cc: Added this new test to
 	load a document, checking some known parts of its structure.
 
-	* glom/libglom/document/bakery/document.cc: write_to_disk(): Create the 
+	* glom/libglom/document/bakery/document.cc: write_to_disk(): Create the
  	parent directory if necessary, instead of failing with a Gio exception.
- 	* test/test_selfhosting_newempty/test_selfhosting_newempty.cc: Saves a new 
+ 	* test/test_selfhosting_newempty/test_selfhosting_newempty.cc: Saves a new
  	file from an example, starts self-hosting of it, and stops self-hosting.
  	This needs work and expansion.
 
 2010-04-20  Murray Cumming  <murrayc murrayc com>
 
 	Python Glom module: Improve sphinx-generated documentation.
-	
-	* glom/python_embed/python_module/py_glom_module.cc: Added class docstring 
-	documentation, based on 
+
+	* glom/python_embed/python_module/py_glom_module.cc: Added class docstring
+	documentation, based on
 	http://library.gnome.org/users/glom/unstable/sec-calculated-fields.html
-	Use reStructuredText format as expected by sphinx and as apparently now 
+	Use reStructuredText format as expected by sphinx and as apparently now
 	use by Python for docstring text.
 
 2010-04-20  Murray Cumming  <murrayc murrayc com>
diff --git a/glom/python_embed/python_module/py_glom_module.cc b/glom/python_embed/python_module/py_glom_module.cc
index 56a7e36..a3468a8 100644
--- a/glom/python_embed/python_module/py_glom_module.cc
+++ b/glom/python_embed/python_module/py_glom_module.cc
@@ -36,15 +36,16 @@ BOOST_PYTHON_MODULE(glom_1_14)
     true, // show Python signatures.
     false); // Don't mention the C++ method signatures in the generated docstrings.
 
-  // Note: Our python docstring documentation is in ReStructuredText format, 
+  // Note: Our python docstring documentation is in ReStructuredText format,
   // because we use sphinx to generate the API reference documentation.
-  // However, sphinx does not seem to allow us to use regular reStructuredText 
-  // - section headings 
+  // However, sphinx does not seem to allow us to use regular reStructuredText
+  // - section headings
   // - :: at the end of a paragraph, instead of on a separate line.
   // TODO: Add # targets so we can link directly to parts such as Testing for Empty Values
-   
-  boost::python::class_<PyGlomRecord>("Record", 
-    "This is the  current record of the current table.\n"
+  // TODO: We can't seem to use reStuctureText sections.
+
+  boost::python::class_<PyGlomRecord>("Record",
+    "This is the  current record of the current table. A :class:`Record` object is passed to field calculations and button scripts, providing access to the values of the fields in that record. The :class:`Record` object passed to field calculations is read-only.\n"
     "\n"
     "Field values\n"
     "  Use record['field_name'] to get the value of a specified field in the current record. For instance, this concatenates the values of the name_first and name_last fields in the current record.\n"
@@ -52,28 +53,13 @@ BOOST_PYTHON_MODULE(glom_1_14)
     "\n"
     "    record['name_first'] + ' ' + record['name_last']\n"
     "\n"
-    "  You may also use this syntax to  set the value of a field in the current record. This is possible in a button script, but not in a field calculation. For instance, this sets the value of the name_first field in the current record.\n"
+    "  You may also use this syntax to set the value of a field in the current record. This is possible in a button script, but not in a field calculation. For instance, this sets the value of the name_first field in the current record.\n"
     "  ::\n"
     "\n"
     "    record['name_first'] = 'Bob'\n"
     "\n"
     "Related Records\n"
-    "  Use record.related['relationship_name'] to get the related records. For instance, this provides the related records for the current record.\n"
-    "  ::\n"
-    "\n"
-    "    record.related['location']\n"
-    "\n"
-    "Single Related Records\n"
-    "  For relationships that specify a single record, you can get the value of a field in that record. For instance, this is the value of the name field in the table indicated by the location relationship (often called location::name).\n"
-    "  ::\n"
-    "\n"
-    "    location_name = record.related['location']['name']\n"
-    "\n"
-    "Multiple Related Records\n"
-    "  For relationships that specify multiple records, you can use the aggregate functions to get overall values. For instance, this provides the sum of all total_price values from all of the lines of the current invoice record. See the :class:`RelatedRecord` class for more aggregate functions.\n"
-    "  ::\n"
-    "\n"
-    "    invoice_total = record.related['invoice_lines'].sum('total_price')\n"
+    "  Use the :attr:`related` attribute to access related records via a relationship."
     "\n"
      "Testing for Empty Values\n"
     "  How you test for empty values depends on the type of field.\n"
@@ -94,27 +80,50 @@ BOOST_PYTHON_MODULE(glom_1_14)
     "      if(record['name_full'] == ''):\n"
     "          return 'No Name'\n"
     "      else:\n"
-    "          return record['name_full']\n"
-    "\n"
-    )
+    "          return record['name_full']\n")
+
+    // boost::python doesn't mention the property types in the generated docstring,
+    // so we must mention it in the properties' docstring text.
     .add_property("table_name", &PyGlomRecord::get_table_name,
-       "The name of the current table.")
+       "The name of the current table as a string.")
     .add_property("connection", &PyGlomRecord::get_connection,
-       "The current database connection for use with the pygda API.")
+       "The current database connection for use with the pygda API. This is a :class:`Gda.Connection` object.")
     .add_property("related", &PyGlomRecord::get_related,
-       "Related records. Use the ['relationship_name'] notation with this object.")
+       ":class:`Related` records. Use the ['relationship_name'] notation with this object.")
 
+    // These can have docstring text too, but sphinx ignores it,
+    // so we mention the [] syntax in the class docstring instead.
+    // TODO: Ask about that / file a sphinx bug.
     .def("__getitem__", &PyGlomRecord::getitem)
     .def("__setitem__", &PyGlomRecord::setitem)
     .def("__len__", &PyGlomRecord::len)
   ;
 
-  boost::python::class_<PyGlomRelated>("Related")
+  boost::python::class_<PyGlomRelated>("Related",
+    "This object provides access to related records via its [] syntax, which takes a relationship name and returns a :class:`RelatedRecord`. For instance, this provides the related records for the current record, via the :attr:`Record.related` attribute\n"
+    "::\n"
+    "\n"
+    "  record.related['location']")
+
     .def("__getitem__", &PyGlomRelated::getitem)
     .def("__len__", &PyGlomRelated::len)
   ;
 
-  boost::python::class_<PyGlomRelatedRecord>("RelatedRecord")
+  boost::python::class_<PyGlomRelatedRecord>("RelatedRecord",
+    "One or more related records, returned by the [] syntax on a :class:`Related` object, such as the :attr:`Record.related` attribute.\n"
+    "\n"
+    "Single Related Records\n"
+    "  For relationships that specify a single record, you can get the value of a field in that record by using the [] synax, providing a field name. For instance, this is the value of the name field in the table indicated by the location relationship (often called location::name).\n"
+    "  ::\n"
+    "\n"
+    "    record.related['location']['name']\n"
+    "\n"
+    "Multiple Related Records\n"
+    "  For relationships that specify multiple records, you can use the aggregate functions to get overall values. For instance, this provides the sum of all total_price values from all of the lines of the current invoice record. See the :class:`RelatedRecord` class for more aggregate functions.\n"
+    "  ::\n"
+    "\n"
+    "    record.related['invoice_lines'].sum('total_price')\n")
+
     .def("sum", &PyGlomRelatedRecord::sum, boost::python::args("field_name"),
       "Add all values of the field in the related records.")
     .def("count", &PyGlomRelatedRecord::sum, boost::python::args("field_name"),
@@ -128,7 +137,8 @@ BOOST_PYTHON_MODULE(glom_1_14)
   ;
 
   boost::python::class_<PyGlomUI>("UI",
-    "A collection of methods to programatically change the Glom UI, performing tasks that might otherwise be done by the user via the mouse and keyboard.")
+    "A collection of methods to programatically change the Glom UI, performing some tasks that might otherwise be done by the user via the mouse and keyboard.  A :class:`UI` object is passed to button scripts, allowing them to control the user interface.")
+
     .def("show_table_details", &PyGlomUI::show_table_details,
       boost::python::args("table_name", "primary_key_value"),
       "Navigate to the specified table, showing its details view for the specified record.")
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]