flux_conf_create(3): pull in man pages

Problem: there are no man pages for flux_conf_t.

Pull them in from flux-core.

Author: garlick

doc/Makefile.am

@@ -12,7 +12,8 @@ MAN3_FILES_PRIMARY = \
 	man3/idset_encode.3 \
 	man3/idset_decode.3 \
 	man3/idset_add.3 \
-	man3/idset_alloc.3
+	man3/idset_alloc.3 \
+	man3/flux_conf_create.3
 
 MAN3_FILES_SECONDARY = \
 	man3/hostlist_destroy.3 \
@@ -59,7 +60,13 @@ MAN3_FILES_SECONDARY = \
 	man3/idset_has_intersection.3 \
 	man3/idset_clear_all.3 \
 	man3/idset_free.3 \
-	man3/idset_free_check.3
+	man3/idset_free_check.3 \
+	man3/flux_conf_incref.3 \
+	man3/flux_conf_decref.3 \
+	man3/flux_conf_copy.3 \
+	man3/flux_conf_unpack.3 \
+	man3/flux_conf_pack.3 \
+	man3/flux_conf_parse.3
 
 RST_FILES  = \
 	$(MAN3_FILES_PRIMARY:.3=.rst)

doc/man3/flux_conf_create.rst

@@ -0,0 +1,94 @@
+===================
+flux_conf_create(3)
+===================
+
+.. default-domain:: c
+
+SYNOPSIS
+========
+
+.. code-block:: c
+
+  #include <flux/conf.h>
+
+  flux_conf_t *flux_conf_create (void);
+
+  const flux_conf_t *flux_conf_incref (const flux_conf_t *conf);
+
+  void flux_conf_decref (const flux_conf_t *conf);
+
+  flux_conf_t *flux_conf_copy (const flux_conf_t *conf);
+
+  int flux_conf_unpack (const flux_conf_t *conf,
+                        flux_error_t *error,
+                        const char *fmt,
+                        ...);
+
+  flux_conf_t *flux_conf_pack (const char *fmt, ...);
+
+  flux_conf_t *flux_conf_parse (const char *path, flux_error_t *error);
+
+Link with :command:`-lflux-conf`.
+
+DESCRIPTION
+===========
+
+Flux configuration is represented by a :type:`flux_conf_t` object.
+
+:func:`flux_conf_create` creates an empty object with a reference
+count of one.
+
+:func:`flux_conf_incref` increments the object reference count.
+:func:`flux_conf_decref` decrements the object reference count
+and destroys it when the count reaches zero.
+
+:func:`flux_conf_copy` duplicates an object.
+
+:func:`flux_conf_unpack` unpacks an object using Jansson
+:func:`json_unpack` style arguments.
+
+:func:`flux_conf_pack` creates an object using Jansson
+:func:`json_pack` style arguments.
+
+:func:`flux_conf_parse` parse a TOML configuration file at :var:`path`
+and creates a config object that contains the result.
+
+ENCODING JSON PAYLOADS
+======================
+
+.. include:: common/json_pack.rst
+
+DECODING JSON PAYLOADS
+======================
+
+.. include:: common/json_unpack.rst
+
+RETURN VALUE
+============
+
+:func:`flux_conf_create`, :func:`flux_conf_copy`, :func:`flux_conf_pack`,
+and :func:`flux_conf_incref` return a :type:`flux_conf_t` object on success.
+On error, NULL is returned, and :var:`errno` is set.
+
+:func:`flux_conf_unpack` returns 0 on success, or -1 on failure with
+:var:`errno` set.
+
+:func:`flux_conf_parse` returns 0 on success.  On error, it returns -1,
+:var:`errno` set, and if :var:`error` is non-NULL, it is filled with
+a human readable error message.
+
+ERRORS
+======
+
+EINVAL
+   Invalid argument.
+
+ENOMEM
+   Out of memory.
+
+RESOURCES
+=========
+
+.. include:: common/resources.rst
+
+TOML: Tom's Oblivious, Minimal Language https://github.com/toml-lang/toml

doc/manpages.py

@@ -69,4 +69,11 @@
     ('man3/idset_alloc','idset_alloc', 'Allocate an id from an idset', [author], 3),
     ('man3/idset_alloc','idset_free', 'Allocate an id from an idset', [author], 3),
     ('man3/idset_alloc','idset_free_check', 'Allocate an id from an idset', [author], 3),
+    ('man3/flux_conf_create','flux_conf_create', 'create a config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_incref', 'take reference on config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_decref', 'drop reference on config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_copy', 'copy config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_unpack', 'parse config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_pack', 'build config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_parse', 'parse TOML config', [author], 3),
 ]