Split C++ api doc into multiple pages

Each page has a table of contents and some headers which make
the pages more readable. Currently breathe has problems with
overloaded files even though I believe I have specified each
signature in an unique way

The included script generate_api_rst.py creates generated
rst files that are included by one static rst file per
subdirectory of dolfin. These static files can be used to
write more descriptive prose or examples if someone feels
like it. Otherwise they will just be short unchanging stubs.

.gitignore

@@ -48,6 +48,7 @@ swigimportinfo.py
 
 # Documentation
 docstrings.i
+generated_rst_files
 
 # Configuration files
 dolfin.conf
@@ -134,4 +135,4 @@ cmake.local
 # Google Test Files
 /GoogleTest/
 
-build/
+build/

doc/generate_api_rst.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python
+#
+# Read doxygen xml files to find all members of the dolfin
+# name space and generate API doc files per subdirectory of
+# dolfin
+#
+# Written by Tormod Landet, 2017
+#
+from __future__ import print_function
+import sys, os, urllib
+import xml.etree.ElementTree as ET
+
+
+DOXYGEN_XML_DIR = 'doxygen/xml'
+API_GEN_DIR = 'generated_rst_files'
+
+
+def get_single_element(parent, name):
+    """
+    Helper to get one unique child element
+    """
+    elems = parent.findall(name)
+    assert len(elems) == 1
+    return elems[0]
+
+
+def get_subdir(hpp_file_name):
+    """
+    Return "subdir" for a path name like
+        /path/to/dolfin/subdir/a_header.h
+    """
+    path_components = hpp_file_name.split(os.sep)
+    path_components_rev = path_components[::-1]
+    idx = path_components_rev.index('dolfin')
+    subdir = path_components_rev[idx - 1]
+    return subdir
+
+
+def get_short_path(hpp_file_name):
+    """
+    Return "dolfin/subdir/a_header.h" for a path name like
+        /path/to/dolfin/subdir/a_header.h
+    """
+    path_components = hpp_file_name.split(os.sep)
+    path_components_rev = path_components[::-1]
+    idx = path_components_rev.index('dolfin')
+    short_path = path_components_rev[:idx + 1]
+    return os.sep.join(short_path[::-1])
+
+
+def visit_compound(c, xml_file_name):
+    """
+    Visit xml node describing a class
+    Classes have their own xml files
+    """
+    kind = c.attrib['kind']
+    name = get_single_element(c, 'compoundname').text
+    hpp_file_name = get_single_element(c, 'location').attrib['file']
+    subdir = get_subdir(hpp_file_name)
+    short_name = name
+
+    insert_info(subdir, kind, name, short_name, xml_file_name, hpp_file_name)
+
+
+def visit_namespace_member(m, xml_file_name, namespace):
+    """
+    Functions and enums are noy described in their own files
+    We visit them one by one as elements in a namespace xml file
+    """
+    kind = m.attrib['kind']
+    hpp_file_name = get_single_element(m, 'location').attrib['file']
+    name = get_single_element(m, 'name').text
+    subdir = get_subdir(hpp_file_name)
+
+    # Make sure we have the required "dolfin::" prefix
+    required_prefix = '%s::' % namespace
+    if not name.startswith(required_prefix):
+        name = required_prefix + name
+    short_name = name[len(required_prefix):]
+
+    # Deal with function overloading
+    if kind == 'function':
+        #name = get_single_element(m, 'definition').text
+        argsstring = get_single_element(m, 'argsstring').text
+        name += argsstring
+
+    insert_info(subdir, kind, name, short_name, xml_file_name, hpp_file_name)
+
+
+all_compounds = {}
+def insert_info(subdir, kind, name, short_name, xml_file_name, hpp_file_name):
+    sd = all_compounds.setdefault(subdir, {})
+    kd = sd.setdefault(kind, {})
+    kd[name] = (short_name, xml_file_name, hpp_file_name)
+
+
+def write_rst(subdir):
+    kinds = all_compounds[subdir]
+    rst_name = os.path.join(API_GEN_DIR, 'api_gen_%s.rst' % subdir)
+    print('Generating', rst_name)
+
+    prev_short_name = ''
+    with open(rst_name, 'wt') as rst:
+        #rst.write('dolfin/%s\n%s' % (subdir, '=' * 80))
+        #rst.write('\nDocumentation for C++ code found in dolfin/%s/*.h\n\n' % subdir)
+        rst.write('\n\n.. contents::\n\n')
+
+        members = [('typedef', 'Type definitions', 'doxygentypedef'),
+                   ('enum', 'Enumerations', 'doxygenenum'),
+                   ('function', 'Functions', 'doxygenfunction'),
+                   ('struct', 'Structures', 'doxygenstruct'),
+                   ('variable', 'Variables', 'doxygenvariable'),
+                   ('class', 'Classes', 'doxygenclass')]
+
+        for kind, kind_name, directive in members:
+            if kind in kinds:
+                # Write header H2
+                rst.write('%s\n%s\n\n' % (kind_name, '-'*70))
+
+                for name, misc in sorted(kinds[kind].items()):
+                    short_name, xml_file_name, hpp_file_name = misc
+                    fn = get_short_path(hpp_file_name)
+
+                    # Write header H3
+                    if short_name != prev_short_name:
+                        rst.write('%s\n%s\n\n' % (short_name, '~'*60))
+                    prev_short_name = short_name
+
+                    # Info about filename
+                    rst.write('C++ documentation for ``%s`` from ``%s``:\n\n' % (short_name, fn))
+
+                    # Breathe autodoc
+                    rst.write('.. %s:: %s\n' % (directive, name))
+                    rst.write('   :project: dolfin\n')
+                    if kind == 'class':
+                        rst.write('   :members:\n')
+                        rst.write('   :undoc-members:\n\n')
+                    else:
+                        rst.write('\n')
+
+
+###############################################################################
+# Loop through xml files of compounds and get class definitions
+print('Parsing doxygen XML files to make groups of %s/*.rst' % API_GEN_DIR)
+xml_files = os.listdir(DOXYGEN_XML_DIR)
+errors = []
+for file_name in xml_files:
+    # Known errors / files we do not care about
+    if (file_name in ('namespacestd.xml', 'indexpage.xml')
+        or file_name.startswith('group__')):
+        continue
+
+    path = os.path.join(DOXYGEN_XML_DIR, file_name)
+    root = ET.parse(path).getroot()
+    compounds = root.findall('compounddef')
+    for c in compounds:
+        try:
+            visit_compound(c, file_name)
+            print('.', end='')
+            sys.stdout.flush()
+        except Exception:
+            errors.append(file_name)
+
+print('\nParsing namespace files')
+
+
+###############################################################################
+# Loop through other elemens in the namespaces
+for namespace in ('dolfin', ):
+    file_name = 'namespace%s.xml' % namespace
+    path = os.path.join(DOXYGEN_XML_DIR, file_name)
+    root = ET.parse(path).getroot()
+    compound = get_single_element(root, 'compounddef')
+    sections = compound.findall('sectiondef')
+    for s in sections:
+        members = s.findall('memberdef')
+        for m in members:
+            visit_namespace_member(m, file_name, namespace)
+print('Done parsing files')
+
+
+for file_name in errors:
+    print('ERROR: could not parse', file_name)
+
+
+# Make output directory
+if not os.path.isdir(API_GEN_DIR):
+    os.mkdir(API_GEN_DIR)
+
+
+# Generate rst files
+for subdir, kinds in sorted(all_compounds.items()):
+    if subdir:
+        write_rst(subdir)
+

doc/source/api.rst

@@ -4,9 +4,30 @@
 API documentation
 =================
 
-.. doxygennamespace:: dolfin
-   :project: dolfin
-   :members:
+The API documentation of the C++ code is split into multiple pages based on the
+location in the dolfin source tree
+
+.. toctree::
+   :maxdepth: 1
+
+   apis/api_adaptivity
+   apis/api_ale
+   apis/api_common
+   apis/api_dolfin.h
+   apis/api_fem
+   apis/api_function
+   apis/api_generation
+   apis/api_geometry
+   apis/api_graph
+   apis/api_io
+   apis/api_la
+   apis/api_log
+   apis/api_math
+   apis/api_mesh
+   apis/api_multistage
+   apis/api_nls
+   apis/api_parameter
+   apis/api_plot
+   apis/api_refinement
 
 
-*Under development*

doc/source/apis/api_adaptivity.rst

@@ -0,0 +1,6 @@
+dolfin/adaptivity
+================================================================================
+Documentation for C++ code found in dolfin/adaptivity/*.h
+
+.. include:: ../../generated_rst_files/api_gen_adaptivity.rst
+

doc/source/apis/api_ale.rst

@@ -0,0 +1,6 @@
+dolfin/ale
+================================================================================
+Documentation for C++ code found in dolfin/ale/*.h
+
+.. include:: ../../generated_rst_files/api_gen_ale.rst
+

doc/source/apis/api_common.rst

@@ -0,0 +1,6 @@
+dolfin/common
+================================================================================
+Documentation for C++ code found in dolfin/common/*.h
+
+.. include:: ../../generated_rst_files/api_gen_common.rst
+

doc/source/apis/api_fem.rst

@@ -0,0 +1,7 @@
+dolfin/fem
+================================================================================
+Documentation for C++ code found in dolfin/fem/*.h
+
+.. include:: ../../generated_rst_files/api_gen_fem.rst
+
+

doc/source/apis/api_function.rst

@@ -0,0 +1,7 @@
+dolfin/function
+================================================================================
+Documentation for C++ code found in dolfin/function/*.h
+
+.. include:: ../../generated_rst_files/api_gen_function.rst
+
+

doc/source/apis/api_gen_refinement.rst

@@ -0,0 +1,6 @@
+dolfin/refinement
+================================================================================
+Documentation for C++ code found in dolfin/refinement/*.h
+
+.. include:: ../../generated_rst_files/api_gen_refinement.rst
+

doc/source/apis/api_generation.rst

@@ -0,0 +1,7 @@
+dolfin/generation
+================================================================================
+Documentation for C++ code found in dolfin/generation/*.h
+
+.. include:: ../../generated_rst_files/api_gen_generation.rst
+
+

doc/source/apis/api_geometry.rst

@@ -0,0 +1,6 @@
+dolfin/geometry
+================================================================================
+Documentation for C++ code found in dolfin/geometry/*.h
+
+.. include:: ../../generated_rst_files/api_gen_geometry.rst
+

doc/source/apis/api_graph.rst

@@ -0,0 +1,6 @@
+dolfin/graph
+================================================================================
+Documentation for C++ code found in dolfin/graph/*.h
+
+.. include:: ../../generated_rst_files/api_gen_graph.rst
+

doc/source/apis/api_io.rst

@@ -0,0 +1,6 @@
+dolfin/io
+================================================================================
+Documentation for C++ code found in dolfin/io/*.h
+
+.. include:: ../../generated_rst_files/api_gen_io.rst
+

doc/source/apis/api_la.rst

@@ -0,0 +1,6 @@
+dolfin/la
+================================================================================
+Documentation for C++ code found in dolfin/la/*.h
+
+.. include:: ../../generated_rst_files/api_gen_la.rst
+

doc/source/apis/api_log.rst

@@ -0,0 +1,6 @@
+dolfin/log
+================================================================================
+Documentation for C++ code found in dolfin/log/*.h
+
+.. include:: ../../generated_rst_files/api_gen_log.rst
+

doc/source/apis/api_math.rst

@@ -0,0 +1,6 @@
+dolfin/math
+================================================================================
+Documentation for C++ code found in dolfin/math/*.h
+
+.. include:: ../../generated_rst_files/api_gen_math.rst
+

doc/source/apis/api_mesh.rst

@@ -0,0 +1,6 @@
+dolfin/mesh
+================================================================================
+Documentation for C++ code found in dolfin/mesh/*.h
+
+.. include:: ../../generated_rst_files/api_gen_mesh.rst
+

doc/source/apis/api_multistage.rst

@@ -0,0 +1,6 @@
+dolfin/multistage
+================================================================================
+Documentation for C++ code found in dolfin/multistage/*.h
+
+.. include:: ../../generated_rst_files/api_gen_multistage.rst
+

doc/source/apis/api_nls.rst

@@ -0,0 +1,6 @@
+dolfin/nls
+================================================================================
+Documentation for C++ code found in dolfin/nls/*.h
+
+.. include:: ../../generated_rst_files/api_gen_nls.rst
+

doc/source/apis/api_parameter.rst

@@ -0,0 +1,6 @@
+dolfin/parameter
+================================================================================
+Documentation for C++ code found in dolfin/parameter/*.h
+
+.. include:: ../../generated_rst_files/api_gen_parameter.rst
+

doc/source/apis/api_plot.rst

@@ -0,0 +1,6 @@
+dolfin/plot
+================================================================================
+Documentation for C++ code found in dolfin/plot/*.h
+
+.. include:: ../../generated_rst_files/api_gen_plot.rst
+

doc/source/apis/api_refinement.rst

@@ -0,0 +1,6 @@
+dolfin/refinement
+================================================================================
+Documentation for C++ code found in dolfin/refinement/*.h
+
+.. include:: ../../generated_rst_files/api_gen_refinement.rst
+