Use breathe + doxygen for API documentation.

doc/CMakeLists.txt

@@ -1,4 +1,5 @@
 add_custom_command(OUTPUT html/index.html
+  COMMAND doxygen
   COMMAND sphinx-build -b html . ../html
   DEPENDS conf.py index.rst)
 add_custom_target(doc DEPENDS html/index.html)

doc/conf.py

@@ -25,10 +25,14 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.ifconfig']
+extensions = ['sphinx.ext.ifconfig', 'breathe']
+
+breathe_projects = { "format": "doxyxml" }
+breathe_default_project = "format"
+breathe_domain_by_extension = {"h" : "cpp"}
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['-templates']
+templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -120,7 +124,7 @@ html_theme = 'sphinxdoc'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['-static']
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

format.h

@@ -181,21 +181,32 @@ class BasicFormatter {
   void operator<<(int value);
 };
 
-// Formatter provides string formatting functionality similar to Python's
+/**
-// str.format. The output is stored in a memory buffer that grows dynamically.
+  \rst
-// Usage:
+  The :class:`Formatter` class provides string formatting
-//
+  functionality similar to Python's `str.format
-//   Formatter out;
+  <http://docs.python.org/3/library/stdtypes.html#str.format>`__.
-//   out("Current point:\n");
+  The output is stored in a memory buffer that grows dynamically.
-//   out("(-{:+f}, {:+f})") << 3.14 << -3.14;
+
-//
+  Usage::
-// This will populate the buffer of the out object with the following output:
+
-//
+     Formatter out;
-//   Current point:
+     out("Current point:\n");
-//   (-3.140000, +3.140000)
+     out("(-{:+f}, {:+f})") << 3.14 << -3.14;
-//
+
-// The buffer can be accessed using Formatter::data() or Formatter::c_str().
+  This will populate the buffer of the ``out`` object with the following
+  output:
+
+  .. code-block:: none
+
+     Current point:
+     (-3.140000, +3.140000)
+
+  The buffer can be accessed using :meth:`data` or :meth:`c_str`.
+  \endrst
+ */
 class Formatter : public BasicFormatter {
+ private:
   enum Type {
     // Numeric types should go first.
     INT, UINT, LONG, ULONG, DOUBLE, LONG_DOUBLE,
@@ -345,10 +356,10 @@ class Formatter : public BasicFormatter {
  public:
   Formatter() : format_(0) { buffer_[0] = 0; }
 
-  // Formats a string appending the output to the internal buffer.
+  /// Formats a string appending the output to the internal buffer.
-  // Arguments are accepted through the returned ArgInserter object
+  /// Arguments are accepted through the returned ArgInserter object
-  // using inserter operator<<.
+  /// using inserter operator<<.
-  internal::ArgInserter operator()(const char *format);
+  internal::ArgInserter operator()(StringRef format);
 
   std::size_t size() const { return buffer_.size(); }
 
@@ -484,9 +495,9 @@ void Formatter::FormatCustomArg(const void *arg, const FormatSpec &spec) {
   Format(af, spec, *static_cast<const T*>(arg));
 }
 
-inline internal::ArgInserter Formatter::operator()(const char *format) {
+inline internal::ArgInserter Formatter::operator()(StringRef format) {
   internal::ArgInserter formatter(this);
-  format_ = format;
+  format_ = format.c_str();
   args_.clear();
   return formatter;
 }