Added basic documentation to package.

rserrano · Dec 3, 2016 · 57f2cad · 57f2cad
1 parent 364fece
commit 57f2cad
Show file tree

Hide file tree

Showing 9 changed files with 113 additions and 168 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -5,14 +5,14 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 # the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
 .PHONY: help
 help:

diff --git a/docs/make.bat b/docs/make.bat
@@ -5,9 +5,9 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
-set I18NSPHINXOPTS=%SPHINXOPTS% .
+set BUILDDIR=build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
+set I18NSPHINXOPTS=%SPHINXOPTS% source
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
 	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%

diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -0,0 +1,30 @@
+geomodelr package
+=================
+
+Submodules
+----------
+
+geomodelr.cpp module
+----------------------
+
+.. automodule:: geomodelr.cpp
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+geomodelr.model module
+----------------------
+
+.. automodule:: geomodelr.model
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: geomodelr
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
diff --git a/docs/conf.py → docs/source/conf.py b/docs/conf.py → docs/source/conf.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 # geomodelr documentation build configuration file, created by
-# sphinx-quickstart on Fri Dec  2 17:18:16 2016.
+# sphinx-quickstart on Fri Dec  2 18:33:03 2016.
 #
 # This file is execfile()d with the current directory set to its
 # containing dir.
@@ -19,7 +19,7 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
-
+import geomodelr
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -31,6 +31,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.mathjax',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -82,7 +83,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = []
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -121,7 +122,8 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+import sphinx_rtd_theme
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

diff --git a/docs/index.rst → docs/source/index.rst b/docs/index.rst → docs/source/index.rst
@@ -7,13 +7,17 @@ Welcome to geomodelr's query tool documentation!
 ================================================
 
 Geomodelr is a web tool for creating geological models easily.
-To create a geological model, go to https://www.geomodelr.com.
-After creating your geological model you might want to use it
-for calculations, geostatistics, simulations, or simply to know
-what geological unit is present at a given path. With this tool 
-you can do all that.
+To create a geological model: 
+- Go to https://www.geomodelr.com.
+- Register.
+- Create your model.
+- Create and download a version of your model as Geological JSON.
 
-To use geomodelr query tool you just need to:
+You might want to use the model for calculations, geostatistics, 
+simulations, or simply to know what geological unit is present 
+at a given point. With this tool you can do all that.
+
+To use geomodelr query tool you just need to::
 
     import geomodelr
     # load your model.
@@ -22,12 +26,12 @@ To use geomodelr query tool you just need to:
     unit, distance = model.closest((1000, 1000, 0.0))
     # do stuff...
     if unit == 'Batholith':
-    ...
+    	...
 
-You can also use this tool as a script.
+You can also use this tool as a script::
 
     $ geomodelr -q /path/to/your/model_version.json
-    x y z
+    1000 1000 0
     Batholith
 
 
@@ -41,12 +45,12 @@ Features
 
 Installation
 ------------
-Install project by calling:
+Install project by calling::
 
     pip install geomodelr
 
 It needs boost libraries and C++ compiler. In case boost libraries are not in a 
-standard location, call it with INCLUDE_DIRS=... and/or LIBRARY_DIRS=...
+standard location, call it with :code:`INCLUDE_DIRS=...` and/or :code:`LIBRARY_DIRS=...`.
 
 Support
 -------
@@ -56,12 +60,14 @@ License
 -------
 This project is licensed under the Affero GPL license https://www.gnu.org/licenses/
 
-Contents:
+Contents
+--------
 
 .. toctree::
    :maxdepth: 2
-
-
+
+   api
+
 
 Indices and tables
 ==================

diff --git a/geomodelr/cpp/geomodel.cpp b/geomodelr/cpp/geomodel.cpp
@@ -58,83 +58,70 @@ BOOST_PYTHON_MODULE(cpp)
 						"the adjacent cross sections.\n\n"
 						"It can be used to query a grid aligned with the model faster, for purposes of\n"
 						"generating a triangulated mesh or a grid.\n\n"
-						"Parameters\n"
-						"---------\n"
-						"point : tuple\n"
+						"Args:\n"
+						"    point : tuple\n"
 						"    The three coordinates of the point in the given coordinate system.\n"
-						"Returns\n"
-						"-------\n"
-						"list(tuple(), ...)\n"
+						"Returns:\n"
+						"    list(tuple(), ...)\n"
 						"    a list with all the possible units, each unit with the distance to the previous\n"
 						"    and next cross sections.\n";
 
 	const char* doc_closest = 	"Given a point, it finds the geological unit that's defined as the closest to\n"
 					"that point.\n\n"
 					"The basic definition of the algorithm is that, given a match between geological units,\n"
 					"the distance from the point to the unit is the sum of the in-section distance to the point\n"
-					"averaged by the distance to the cross section.\n"
-					"Parameters\n"
-					"---------\n"
-					"point : tuple\n"
+					"averaged by the distance to the cross section.\n\n"
+					"Args:\n"
+					"    point : tuple\n"
 					"    The three coordinates of the point in the given coordinate system.\n"
-					"Returns\n"
-					"-------\n"
-					"tuple\n"
+					"Returns:\n"
+					"    tuple\n"
 					"    A tuple with the geological unit and the defined distance to that unit.";
 
 	const char* doc_closest_topo =	"Same as closest but it returns (AIR, inf) if the point is above the topography.\n\n"
 					"It first looks if the point is above the topography and returns (AIR, inf) in that case.\n"
 					"Otherwise it returns the same as closest.\n\n"
-					"Parameters\n"
-					"---------\n"
-					"point : tuple\n"
+					"Args:\n"
+					"    point : tuple\n"
 					"    The three coordinates (easting, northing, altitude a.s.l) of the point in the given coordinate system.\n"
-					"Returns\n"
-					"-------\n"
-					"tuple\n"
+					"Returns:\n"
+					"    tuple\n"
 					"    A tuple with the geological unit and the defined distance to that unit or AIR if it's\n"
 					"    above the topography.";
 
-	const char* doc_height ="Returns the height at the given point at the topography.\n\n"
+	const char* doc_height ="Returns: the height at the given point at the topography.\n\n"
 				"It returns the height at the point stored in the topography. In case the point it's outside the bounds of\n"
 				"the model, it returns the height of the closest point inside.\n\n"
-				"Parameters\n"
-				"----------\n"
-				"point tuple\n\n"
+				"Args:\n"
+				"    point tuple\n\n"
 				"    The two coordinates (easting, northing) of the point in the given coordinate system.\n\n"
-				"Returns\n"
-				"-------\n"
-				"real\n"
+				"Returns:\n"
+				"    real\n"
 				"    The height as stored in the topography.\n";
 
 	const char* doc_model_point =	"Translates the point to internal coordinates\n\n"
 					"It returns in-section x coordinate, in-section y coordinate, cut coordinate\n\n"
-					"Parameters\n"
-					"----------\n"
-					"point : tuple\n"
+					"Args:\n"
+					"    point : tuple\n"
 					"    The three coordinates (esting, norting, altitute a.s.l) of the point in the given coordinate system.\n"
-					"Returns\n"
-					"----------\n"
-					"tuple\n"
+					"Returns:\n"
+					"    tuple\n"
 					"    The point in the internal coordinate system.\n";
 
 	const char* doc_inverse_point =	"From internal coordinates, it returns the point in the given coordinate system.\n\n"
 					"It returns easting, northing and altitude from in-section x coordinate, in-section\n"
 					"y coordinate, cut coordinate\n\n"
-					"Parameters\n"
-					"----------\n"
-					"point : tuple\n"
+					"Args:\n"
+					"    point : tuple\n"
 					"    The three coordinates of the internal point.\n"
-					"Returns\n"
-					"----------\n"
-					"tuple\n"
+					"Returns:\n"
+					"    tuple\n"
 					"    The point in the given coordinate system\n";
 
 	const char* doc_verb =	"Sets the operations as verbose.\n\n"
 				"When creating the model, it will advice the user of problems with geometries or matchings.\n\n"
-				"Parameters\n"
-				"----------\n"
-				"verbose : boolean\n"
+				"Args:\n"
+				"    verbose : boolean\n"
 				"    if geomodelr should be verbose when creating the model.\n";
 
 	// Register exception.

diff --git a/geomodelr/model.py b/geomodelr/model.py
@@ -71,19 +71,18 @@ def __init__( self, geolojson ):
         Initializes the geological model from a Geological JSON 
         file created in www.geomodelr.com.
         
-        You can create a free user at geomodelr.com and it will allow you to create the 
+        You can create a free user at https://geomodelr.com and it will allow you to create the 
         Geological Model. After you are finished, create a version and it will allow you
         to download it as a Geological JSON. You can use this constructor by loading the 
-        json, like this:
+        json, like this::
         
-        import json
-        import geomodelr
-        mfile = open('/path/to/your/version.json')
-        geomodel = geomodelr.GeologicalModel(json.loads(mfile.read()))
+            import json
+            import geomodelr
+            mfile = open('/path/to/your/version.json')
+            geomodel = geomodelr.GeologicalModel(json.loads(mfile.read()))
 
-        Parameters
-        ----------
-        geolojson : dict
+        Parameters:
+            geolojson : dict
             The Geological JSON
         """
         self.geojson = geolojson
@@ -140,9 +139,8 @@ def print_information( self, verbose=False ):
         Prints the version, coordinate system and valid coordinates 
         that the geological model takes.
         
-        Parameters
-        ----------
-        verbose : boolean
+        Parameters:
+            verbose : boolean
             You can print more information with verbose=True.
         """
         # Get name of the study.
@@ -228,14 +226,12 @@ def intersect_plane( self, plane ):
         Takes a plane represented with its four corners and returns the set 
         of lines that intersect that plane with the faults.
         
-        Arguments
-        ---------
-        plane : list
+        Args:
+            plane : list
             list with the four corners of the plane that we want to intersect the fault with.
         
-        Returns
-        -------
-        dict
+        Returns:
+            dict
             a dictionary with fault names as keys, and lines, (list of points) as values.
             the coordinates go from the lower left corner, (0.0, 0.0).
         """
@@ -250,14 +246,12 @@ def intersect_planes( self, planes ):
         the first plane lower corner, and increase by dist(plane[i][0], plane[i][1]) for the
         next plane.
         
-        Arguments
-        ---------
-        plane : list
+        Args:
+            plane : list
             list with planes. Each plane has a list with four corners that we want to intersect the fault with.
         
-        Returns
-        -------
-        dict
+        Returns:
+            dict
             a dictionary with fault names as keys, and lines, (list of points) as values.
         """
         return faults.find_faults_multiple_planes_intersection( self.joined_faults, planes )
@@ -304,13 +298,11 @@ def model_from_file(filename):
     from the file path. The geological model is a model of 
     geomodelr.com, downloaded as a version.
     
-    Arguments
-    ---------
-    filename : str
+    Args:
+        filename : str
         The path to the Geological JSON file downloaded from Geomodelr.com.
-    Returns
-    -------
-    GeologicalModel
+    Returns:
+        GeologicalModel
         The output Geological model to query the geological units freely.
     """
     f = open(filename)