Doc fixes

inducer · May 27, 2014 · 047bf07 · 047bf07
1 parent 5cf4f58
commit 047bf07
Show file tree

Hide file tree

Showing 9 changed files with 169 additions and 109 deletions.
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
@@ -1,2 +1,2 @@
 {% extends "!layout.html" %}
-{% set css_files = css_files + ['_static/akdoc.css']%}
+{% set bootswatch_css_custom = ['_static/akdoc.css']%}
diff --git a/doc/conf.py b/doc/conf.py
@@ -23,7 +23,11 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-#extensions = []
+extensions = [
+        'sphinx.ext.autodoc',
+        'sphinx.ext.viewcode',
+        'sphinx.ext.intersphinx',
+        ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

diff --git a/doc/geometry.rst b/doc/geometry.rst
@@ -0,0 +1,4 @@
+Geometry Generation
+===================
+
+.. automodule:: meshpy.geometry
diff --git a/doc/gmsh.rst b/doc/gmsh.rst
@@ -0,0 +1,5 @@
+Gmsh interface
+===================
+
+.. automodule:: meshpy.gmsh_reader
+
diff --git a/doc/index.rst b/doc/index.rst
@@ -1,20 +1,19 @@
-.. MeshPy documentation master file, created by sphinx-quickstart on Tue Jul  1 12:35:03 2008.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to MeshPy's documentation!
 ==================================
 
 MeshPy offers quality triangular and tetrahedral mesh generation for Python.
 Meshes of this type are chiefly used in finite-element simulation codes, but
 also have many other applications ranging from computer graphics to robotics.
 
-
 In order to generate these 2D and 3D meshes, MeshPy provides Python interfaces
-to two well-regarded mesh generators, `Triangle
-<http://www.cs.cmu.edu/~quake/triangle.html>`_ by J. Shewchuk and `TetGen
-<http://tetgen.berlios.de/>`_ by Hang Si. Both are included in the package in
-slightly modified versions.
+to a few well-regarded mesh generators: 
+
+* `Triangle <http://www.cs.cmu.edu/~quake/triangle.html>`_ by J. Shewchuk.
+* `TetGen <http://tetgen.berlios.de/>`_ by Hang Si.
+* `Gmsh <http://geuz.org/gmsh/>`_ by Christophe Geuzaine and Jean-François Remacle.
+
+Triangle and TetGen are included in the package in slightly modified versions. Gmsh
+is called as a subprocess.
 
 Show me! I need examples!
 -------------------------
@@ -78,7 +77,9 @@ Contents
     :maxdepth: 2
 
     installation
-    reference
+    tri-tet
+    geometry
+    gmsh
     faq
 
 MeshPy has its own `web page <http://mathema.tician.de/software/meshpy>`_, where you

diff --git a/doc/reference.rst → doc/tri-tet.rst b/doc/reference.rst → doc/tri-tet.rst
@@ -1,5 +1,5 @@
-Reference Documentation
-=======================
+Triangle/TetGen interface
+=========================
 
 Some common notions
 -------------------
@@ -363,51 +363,3 @@ Some common notions
 
     :param insert_points: a :class:`MeshInfo` object specifying additional points to be inserted
 
-.. data:: EXT_OPEN
-.. data:: EXT_CLOSED_IN_RZ
-
-.. function:: generate_extrusion(rz_points, base_shape, closure=EXT_OPEN, point_idx_offset=0, ring_point_indices=None, ring_markers=None, rz_closure_marker=0)
-
-    Extrude a given connected *base_shape* (a list of (x,y) points)
-    along the z axis. For each step in the extrusion, the base shape
-    is multiplied by a radius and shifted in the z direction. Radius
-    and z offset are given by *rz_points*, which is a list of
-    (r, z) tuples.
-
-    Returns *(points, facets, facet_holestarts, markers)*, where *points* is a list
-    of (3D) points and facets is a list of polygons. Each polygon is, in turn,
-    represented by a tuple of indices into *points*. If *point_idx_offset* is
-    not zero, these indices start at that number. *markers* is a list equal in
-    length to *facets*, each specifying the facet marker of that facet.
-    *facet_holestarts* is also equal in length to *facets*, each element is a list of
-    hole starting points for the corresponding facet.
-
-    Use :meth:`MeshInfo.set_facets_ex` to add the extrusion to a :class:`MeshInfo`
-    structure.
-
-    The extrusion proceeds by generating quadrilaterals connecting each
-    ring.  If any given radius in *rz_points* is 0, triangle fans are
-    produced instead of quads to provide non-degenerate closure.
-
-    If *closure* is :data:`EXT_OPEN`, no efforts are made to put end caps on the
-    extrusion.
-
-    If *closure* is :data:`EXT_CLOSED_IN_RZ`, then a torus-like structure
-    is assumed and the last ring is just connected to the first.
-
-    If *ring_markers* is not None, it is an list of markers added to each
-    ring. There should be len(rz_points)-1 entries in this list.
-    If rings are added because of closure options, they receive the
-    corresponding *XXX_closure_marker*.  If *facet_markers* is given, this function
-    returns (points, facets, markers), where markers is is a list containing
-    a marker for each generated facet. Unspecified markers generally
-    default to 0.
-
-    If *ring_point_indices* is given, it must be a list of the same
-    length as *rz_points*. Each entry in the list may either be None,
-    or a list of point indices. This list must contain the same number
-    of points as the *base_shape*; it is taken as the indices of
-    pre-existing points that are to be used for the given ring, instead
-    of generating new points.
-
-.. function:: generate_surface_of_revolution(rz_points, closure=EXT_OPEN, radial_subdiv=16, point_idx_offset=0, ring_point_indices=None, ring_markers=None, rz_closure_marker=0)
diff --git a/meshpy/geometry.py b/meshpy/geometry.py
@@ -1,6 +1,40 @@
 from __future__ import division
 import numpy as np
 
+__doc__ = """
+
+Geometry builder
+----------------
+
+.. autoclass:: GeometryBuilder
+
+Geometries
+----------
+
+These functions are designed so that their output can be splat-passed to
+:meth:`GeometryBuilder.add_geometry`::
+
+    builder = GeometryBuilder()
+    builder.add_geometry(*make_ball(10))
+
+.. autoclass:: Marker
+    :members:
+    :undoc-members:
+
+.. autofunction:: make_box
+.. autofunction:: make_circle
+.. autofunction:: make_ball
+.. autofunction:: make_cylinder
+
+Extrusions and surfaces of revolution
+-------------------------------------
+
+.. data:: EXT_OPEN
+.. data:: EXT_CLOSED_IN_RZ
+
+.. autofunction:: generate_extrusion
+.. autofunction:: generate_surface_of_revolution
+"""
 
 # {{{ geometry building
 
@@ -36,6 +70,14 @@ def offset_point_indices(facets, offset):
 
 
 class GeometryBuilder(object):
+    """
+    .. automethod:: add_geometry
+    .. automethod:: set
+    .. automethod:: wrap_in_box
+    .. automethod:: bounding_box
+    .. automethod:: center
+    .. automethod:: apply_transform
+    """
     def __init__(self):
         self.points = []
         self.facets = []
@@ -96,6 +138,10 @@ def dimensions(self):
         return len(self.points[0])
 
     def set(self, mesh_info):
+        """Transfer the built geometry into a :class:`meshpy.triangle.MeshInfo`
+        or a :class:`meshpy.tet.MeshInfo`.
+        """
+
         mesh_info.set_points(self.points, self.point_markers)
         if self.facet_hole_starts or is_multi_polygon(self.facets):
             mesh_info.set_facets_ex(self.facets,

diff --git a/meshpy/gmsh.py b/meshpy/gmsh.py
@@ -2,8 +2,8 @@ class GmshError(RuntimeError):
     pass
 
 
+# {{{ tools
 
-# tools -----------------------------------------------------------------------
 def _erase_dir(dir):
     from os import listdir, unlink, rmdir
     from os.path import join
@@ -12,7 +12,6 @@ def _erase_dir(dir):
     rmdir(dir)
 
 
-
 class _TempDirManager(object):
     def __init__(self):
         from tempfile import mkdtemp
@@ -29,10 +28,8 @@ def error_clean_up(self):
         _erase_dir(self.path)
 
 
-
-
 class GmshRunner(object):
-    def __init__(self, source, dimensions, order=None, 
+    def __init__(self, source, dimensions, order=None,
             incomplete_elements=None, other_options=[],
             extension="geo", gmsh_executable="gmsh"):
         self.source = source
@@ -70,8 +67,9 @@ def __enter__(self):
                 cmdline.extend(["-order", str(self.order)])
 
             if self.incomplete_elements is not None:
-                cmdline.extend(["-string", 
-                    "Mesh.SecondOrderIncomplete = %d;" % int(self.incomplete_elements)])
+                cmdline.extend(["-string",
+                    "Mesh.SecondOrderIncomplete = %d;"
+                    % int(self.incomplete_elements)])
 
             cmdline.extend(self.other_options)
             cmdline.append(source_file_name)