Merge pull request QuantEcon#164 from QuantEcon/update-doc-api

mmcky · mmcky · commit c81cf7e37daf · 2015-08-17T10:18:50.000-04:00
Update readthedocs to include all files and new sub packages in quantecon
diff --git a/docs/qe_apidoc.py b/docs/qe_apidoc.py
@@ -39,6 +39,7 @@
 ######################
 ## String Templates ##
 ######################
+
 module_template = """{mod_name}
 {equals}
 
@@ -48,6 +49,15 @@
     :show-inheritance:
 """
 
+markov_module_template = """{mod_name}
+{equals}
+
+.. automodule:: quantecon.markov.{mod_name}
+    :members:
+    :undoc-members:
+    :show-inheritance:
+"""
+
 model_module_template = """{mod_name}
 {equals}
 
@@ -57,6 +67,33 @@
     :show-inheritance:
 """
 
+solow_model_module_template = """{mod_name}
+{equals}
+
+.. automodule:: quantecon.models.solow.{mod_name}
+    :members:
+    :undoc-members:
+    :show-inheritance:
+"""
+
+random_module_template = """{mod_name}
+{equals}
+
+.. automodule:: quantecon.random.{mod_name}
+    :members:
+    :undoc-members:
+    :show-inheritance:
+"""
+
+util_module_template = """{mod_name}
+{equals}
+
+.. automodule:: quantecon.util.{mod_name}
+    :members:
+    :undoc-members:
+    :show-inheritance:
+"""
+
 all_index_template = """=======================
 QuantEcon documentation
 =======================
@@ -81,16 +118,24 @@
 QuantEcon documentation
 =======================
 
-The `quantecon` python library is composed of two main section: models
-and tools. The models section contains implementations of standard
+The `quantecon` python library consists of a number of modules which
+includes economic models (models), markov chains (markov), random 
+generation utilities (random), a collection of tools (tools), 
+and other utilities (util) which are 
+mainly used by developers internal to the package. 
+
+The models section, for example, contains implementations of standard
 models, many of which are discussed in lectures on the website `quant-
 econ.net <http://quant-econ.net>`_.
 
 .. toctree::
    :maxdepth: 2
 
+   markov
    models
+   random
    tools
+   util
 
 Indices and tables
 ==================
@@ -147,46 +192,108 @@ def all_auto():
 
 
 def model_tool():
+    # list file names with markov
+    markov_files = glob("../quantecon/markov/[a-z0-9]*.py")
+    markov = map(lambda x: x.split('/')[-1][:-3], markov_files)
+    # Alphabetize
+    markov.sort()
+
     # list file names with models
     mod_files = glob("../quantecon/models/[a-z0-9]*.py")
     models = map(lambda x: x.split('/')[-1][:-3], mod_files)
     # Alphabetize
     models.sort()
 
-    # list file names of tools
+    # list file names with models.solow
+    solow_files = glob("../quantecon/models/solow/[a-z0-9]*.py")
+    solow = map(lambda x: x.split('/')[-1][:-3], solow_files)
+    # Alphabetize
+    solow.sort()
+
+    # list file names with random
+    random_files = glob("../quantecon/random/[a-z0-9]*.py")
+    random = map(lambda x: x.split('/')[-1][:-3], random_files)
+    # Alphabetize
+    random.sort()
+
+    # list file names of tools (base level modules)
     tool_files = glob("../quantecon/[a-z0-9]*.py")
     tools = map(lambda x: x.split('/')[-1][:-3], tool_files)
     # Alphabetize
+    tools.remove("version")
     tools.sort()
+    
+    # list file names of utilities
+    util_files = glob("../quantecon/util/[a-z0-9]*.py")
+    util = map(lambda x: x.split('/')[-1][:-3], util_files)
+    # Alphabetize
+    util.sort()
 
-    for folder in ["models", "tools"]:
+    for folder in ["markov","models","models/solow","random","tools","util"]:
         if not os.path.exists(source_join(folder)):
             os.makedirs(source_join(folder))
 
+    # Write file for each markov file
+    for mod in markov:
+        new_path = os.path.join("source", "markov", mod + ".rst")
+        with open(new_path, "w") as f:
+            equals = "=" * len(mod)
+            f.write(markov_module_template.format(mod_name=mod, equals=equals))
+
     # Write file for each model
     for mod in models:
         new_path = os.path.join("source", "models", mod + ".rst")
         with open(new_path, "w") as f:
             equals = "=" * len(mod)
             f.write(model_module_template.format(mod_name=mod, equals=equals))
 
-    # Write file for each tool
+    # Write file for each model.solow
+    for mod in solow:
+        new_path = os.path.join("source", "models", "solow", mod + ".rst")
+        with open(new_path, "w") as f:
+            equals = "=" * len(mod)
+            f.write(solow_model_module_template.format(mod_name=mod, equals=equals))  
+
+    # Write file for each random file
+    for mod in random:
+        new_path = os.path.join("source", "random", mod + ".rst")
+        with open(new_path, "w") as f:
+            equals = "=" * len(mod)
+            f.write(random_module_template.format(mod_name=mod, equals=equals))
+
+    # Write file for each tool (base level modules)
     for mod in tools:
         new_path = os.path.join("source", "tools", mod + ".rst")
         with open(new_path, "w") as f:
             equals = "=" * len(mod)
             f.write(module_template.format(mod_name=mod, equals=equals))
 
+    # Write file for each utility
+    for mod in util:
+        new_path = os.path.join("source", "util", mod + ".rst")
+        with open(new_path, "w") as f:
+            equals = "=" * len(mod)
+            f.write(util_module_template.format(mod_name=mod, equals=equals))
+
     # write (index|models|tools).rst file to include autogenerated files
     with open(source_join("index.rst"), "w") as index:
         index.write(split_index_template)
 
+    mark = "markov/" + "\n   markov/".join(markov)
     mods = "models/" + "\n   models/".join(models)
+    mods = mods  + "\n   solow/"                                 #Add solow sub directory to models
+    rand = "random/" + "\n   random/".join(random)
     tlz = "tools/" + "\n   tools/".join(tools)
-    toc_tree_list = {"models": mods,
-                     "tools": tlz}
-
-    for f_name in ("models", "tools"):
+    utls = "util/" + "\n   util/".join(util)
+    #-TocTree-#
+    toc_tree_list = {"markov":mark,
+                     "models": mods,
+                     "tools": tlz,
+                     "random":rand,
+                     "util":utls,
+                     }
+
+    for f_name in ("markov","models","random","tools","util"):
         with open(source_join(f_name + ".rst"), "w") as f:
             temp = split_file_template.format(name=f_name.capitalize(),
                                               equals="="*len(f_name),
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -105,9 +105,10 @@ def __getattr__(cls, name):
 # built documents.
 #
 # The short X.Y version.
-version = '0.1.3'
+from version import version as quantecon_version
+version = quantecon_version
 # The full version, including alpha/beta/rc tags.
-release = '0.1.3'
+release = quantecon_version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -2,16 +2,24 @@
 QuantEcon documentation
 =======================
 
-The `quantecon` python library is composed of two main section: models
-and tools. The models section contains implementations of standard
+The `quantecon` python library consists of a number of modules which
+includes economic models (models), markov chains (markov), random 
+generation utilities (random), a collection of tools (tools), 
+and other utilities (util) which are 
+mainly used by developers internal to the package. 
+
+The models section, for example, contains implementations of standard
 models, many of which are discussed in lectures on the website `quant-
 econ.net <http://quant-econ.net>`_.
 
 .. toctree::
    :maxdepth: 2
 
+   markov
    models
+   random
    tools
+   util
 
 Indices and tables
 ==================
diff --git a/docs/source/markov.rst b/docs/source/markov.rst
@@ -0,0 +1,10 @@
+Markov
+======
+
+.. toctree::
+   :maxdepth: 2
+
+   markov/approximation
+   markov/core
+   markov/gth_solve
+   markov/random
diff --git a/docs/source/markov/approximation.rst b/docs/source/markov/approximation.rst
@@ -0,0 +1,7 @@
+approximation
+=============
+
+.. automodule:: quantecon.markov.approximation
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/markov/core.rst b/docs/source/markov/core.rst
@@ -1,7 +1,7 @@
-tauchen
-=======
+core
+====
 
-.. automodule:: quantecon.tauchen
+.. automodule:: quantecon.markov.core
     :members:
     :undoc-members:
     :show-inheritance:
diff --git a/docs/source/markov/gth_solve.rst b/docs/source/markov/gth_solve.rst
@@ -0,0 +1,7 @@
+gth_solve
+=========
+
+.. automodule:: quantecon.markov.gth_solve
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/markov/random.rst b/docs/source/markov/random.rst
@@ -0,0 +1,7 @@
+random
+======
+
+.. automodule:: quantecon.markov.random
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/models.rst b/docs/source/models.rst
@@ -11,3 +11,4 @@ Models
    models/lucastree
    models/odu
    models/optgrowth
+   solow/
diff --git a/docs/source/models/solow/ces.rst b/docs/source/models/solow/ces.rst
@@ -0,0 +1,7 @@
+ces
+===
+
+.. automodule:: quantecon.models.solow.ces
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/models/solow/cobb_douglas.rst b/docs/source/models/solow/cobb_douglas.rst
@@ -0,0 +1,7 @@
+cobb_douglas
+============
+
+.. automodule:: quantecon.models.solow.cobb_douglas
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/models/solow/impulse_response.rst b/docs/source/models/solow/impulse_response.rst
@@ -0,0 +1,7 @@
+impulse_response
+================
+
+.. automodule:: quantecon.models.solow.impulse_response
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/models/solow/model.rst b/docs/source/models/solow/model.rst
@@ -0,0 +1,7 @@
+model
+=====
+
+.. automodule:: quantecon.models.solow.model
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/random.rst b/docs/source/random.rst
@@ -0,0 +1,7 @@
+Random
+======
+
+.. toctree::
+   :maxdepth: 2
+
+   random/utilities
diff --git a/docs/source/random/utilities.rst b/docs/source/random/utilities.rst
@@ -0,0 +1,7 @@
+utilities
+=========
+
+.. automodule:: quantecon.random.utilities
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/tools.rst b/docs/source/tools.rst
@@ -5,27 +5,26 @@ Tools
    :maxdepth: 2
 
    tools/arma
-
+   tools/cartesian
    tools/ce_util
+   tools/common_messages
    tools/compute_fp
    tools/discrete_rv
    tools/distributions
    tools/ecdf
    tools/estspec
+   tools/external
    tools/graph_tools
    tools/gridtools
-   tools/gth_solve
    tools/ivp
    tools/kalman
    tools/lae
    tools/lqcontrol
    tools/lqnash
    tools/lss
    tools/matrix_eqn
-   tools/mc_tools
    tools/quad
    tools/quadsums
    tools/rank_nullspace
    tools/robustlq
-   tools/tauchen
-   tools/version
+   tools/timing
diff --git a/docs/source/tools/cartesian.rst b/docs/source/tools/cartesian.rst
@@ -1,7 +1,7 @@
-gridtools
+cartesian
 =========
 
-.. automodule:: quantecon.gridtools
+.. automodule:: quantecon.cartesian
     :members:
     :undoc-members:
     :show-inheritance:
diff --git a/docs/source/tools/common_messages.rst b/docs/source/tools/common_messages.rst
@@ -0,0 +1,7 @@
+common_messages
+===============
+
+.. automodule:: quantecon.common_messages
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/tools/external.rst b/docs/source/tools/external.rst
@@ -1,7 +1,7 @@
-mc_tools
+external
 ========
 
-.. automodule:: quantecon.mc_tools
+.. automodule:: quantecon.external
     :members:
     :undoc-members:
     :show-inheritance:
diff --git a/docs/source/tools/graph_tools.rst b/docs/source/tools/graph_tools.rst
diff --git a/docs/source/tools/gridtools.rst b/docs/source/tools/gridtools.rst
diff --git a/docs/source/tools/timing.rst b/docs/source/tools/timing.rst
diff --git a/docs/source/util.rst b/docs/source/util.rst
diff --git a/docs/source/util/array.rst b/docs/source/util/array.rst
diff --git a/docs/source/util/random.rst b/docs/source/util/random.rst
diff --git a/quantecon/random/utilities.py b/quantecon/random/utilities.py
