docs: wip document shapelibs, move from shapelib-toml

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst
index f99567f345629e9555217c776fee6f4072dbfb1a..422e36ee79124319591c175ad5db8fa9cf87592e 100644 (file)
--- a/docs/shapelibs.rst
+++ b/docs/shapelibs.rst
@@ -150,6 +150,15 @@ See the existing examples to see what item names usually look like.
 Parameters
 ----------
 
+ * ``inherit`` (string: group name).  Causes this group to inherit
+   every parameter (except ``files``) from the group named by
+   ``inherit`` (recursively, if applicable).
+
+   When inheritance is happening, there is of course a difference
+   between leaving a value unspecified, and specifying it to have
+   the usual default value: the latter would override any inherited
+   setting.
+
  * ``item_prefix``, ``item_suffix`` (strings, default ``""``).
    Prepaended and appended to ``ITEM-SPEC`` in ``files`` to
    produce the item name.
@@ -163,4 +172,3 @@ Parameters
    If both are specified, the group parameter is used as a template.
    ``_s`` is replaced by the sort extra field from the ``files`` list
    ``_c`` is replaced by the colour, if applicable.
-

diff --git a/src/shapelib-toml.rs b/src/shapelib-toml.rs
index 8874042edde0c3839a8e4d69922da681be34da83..33691703418e33a051e216447cd792285917ca16 100644 (file)
--- a/src/shapelib-toml.rs
+++ b/src/shapelib-toml.rs
@@ -18,23 +18,9 @@ pub struct GroupDefn {
   #[serde(flatten)] pub d: GroupDetails,
 }
 
-/// Details for a group of pieces. See also [`GroupDefn`].
-///
-/// This is separate from `GroupDefn` only to make the
-/// implementation convenient (for complicated reasons).  At the
-/// library TOML file level, there is no meaningful difference between
-/// the fields in this struct, and the ones in `GroupDefn`
 #[derive(Debug,Deserialize)]
 pub struct GroupDetails {
-  /// Causes this group to inherit every setting from the `GroupDefn`
-  /// and `GroupDetails` of the group named by `inherit` (recursively,
-  /// if applicable).
-  ///
-  /// When inheritance is happening, there is of course a difference
-  /// between leaving a value unspecified, and specifying it to have
-  /// the usual default value: the latter would override any inherited
-  /// setting.
-  #[cfg(doc)]
+  #[cfg(doc)] // handled specially
   inherit: String,
 
   /// Should be either a 1- or 2- element list, x and y, or just one