Initial version, remains a lot of docstring fixes

buzzard/__init__.py

@@ -1,6 +1,5 @@
-"""Welcome to buzzard, https://github.com/airware/buzzard
-
-buzzard should always be imported the first time from the main thread
+"""
+When you import :code:`buzzard` for the first time, you should always do it from the main thread.
 """
 
 # Import osgeo before cv2

buzzard/algo/_slopes.py

@@ -25,19 +25,24 @@ def _calcdzdy(dsm, reso, dtype):
 
 def create_slopes(dsm, reso, dtype=np.float32, crop=False):
     '''
-    Compute the slopes from dsm
-    - dsm: (M, N) numpy array
-    - reso: float or (float, float)
-      - (resox, resoy) = reso: Spanning of a pixel in space
-      - Should be in the same unit as dsm's values
-      - If a single float is given, it is interpreted as (reso, -reso)
-    - dtype: numpy dtype
-      - Output dtype
-    - crop: bool
-      - Cropping of output array
-    - return value: numpy array
-      - If crop: (M - 1, N - 1)
-      - Else: (M, N)
+    Compute the slopes from dsm:
+
+    Args:
+        dsm: (M, N) numpy array
+        reso: float or (float, float)
+
+            * (resox, resoy) = reso: Spanning of a pixel in space
+            * Should be in the same unit as dsm's values
+            * If a single float is given, it is interpreted as (reso, -reso)
+        dtype: numpy dtype
+
+            * Output dtype
+        crop: bool
+
+            * Cropping of output array
+
+    Returns:
+        numpy.array: If crop: (M - 1, N - 1) Else: (M, N)
     '''
     try:
         reso = tuple(reso)

buzzard/srs/__init__.py

@@ -1,5 +1,6 @@
-"""Collection of spatial references manipuation utilities,
-might be filled/improved/moved in the future
+"""Collection of spatial references manipulation utilities,
+
+Will be filled/improved/moved in the future
 """
 
 from osgeo import gdal, osr, ogr

docs/buzzard.algo.rst

@@ -1,10 +1,12 @@
-buzzard.algo package
-====================
-
-Module contents
----------------
+buzzard.algo
+============
 
 .. automodule:: buzzard.algo
     :members:
     :undoc-members:
     :show-inheritance:
+
+Functions
+---------
+
+.. autofunction:: buzzard.algo.create_slopes

docs/buzzard.rst

@@ -1,18 +1,63 @@
-buzzard package
-===============
+buzzard
+=======
 
-Subpackages
------------
+.. automodule:: buzzard
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
-.. toctree::
+Classes
+-------
 
-    buzzard.algo
-    buzzard.srs
+.. autoclass:: buzzard.Footprint
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
-Module contents
----------------
+.. autoclass:: buzzard.DataSource
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
-.. automodule:: buzzard
+.. autoclass:: buzzard.Proxy
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: buzzard.Raster
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: buzzard.Vector
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: buzzard.RasterPhysical
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: buzzard.RasterRecipe
     :members:
     :undoc-members:
     :show-inheritance:
+
+.. autoclass:: buzzard.Env
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Data
+----
+
+.. autodata:: buzzard.env
+
+Subpackages
+-----------
+
+.. toctree::
+
+    buzzard.algo
+    buzzard.srs

docs/buzzard.srs.rst

@@ -1,10 +1,30 @@
-buzzard.srs package
-===================
-
-Module contents
----------------
+buzzard.srs
+===========
 
 .. automodule:: buzzard.srs
     :members:
     :undoc-members:
     :show-inheritance:
+
+Classes
+-------
+
+.. autoclass:: buzzard.srs.Analysis
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. Functions Autogenerated by automodule
+.. ---------
+
+.. .. autofunction:: buzzard.srs.wkt_of_any
+
+.. .. autofunction:: buzzard.srs.wkt_same
+
+.. .. autofunction:: buzzard.srs.wkt_of_file
+
+
+Attributes
+----------
+
+.. autoattribute:: buzzard.srs.REG

docs/conf.py

@@ -14,39 +14,31 @@
 
 import os
 import sys
+from datetime import datetime
 sys.path.insert(0, os.path.abspath('../'))
 
 
 # -- Project information -----------------------------------------------------
 
 project = 'buzzard'
-copyright = '2018, Airware'
-author = 'Nicolas Goguey, Hervé Nivon'
-
-# The short X.Y version
+copyright = u'%s, Airware' % datetime.now().year
+author = 'Airware'
 version = ''
-# The full version, including alpha/beta/rc tags
-release = ''
-
+release = version
 
 # -- General configuration ---------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
 # 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.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.coverage',
     'sphinx.ext.doctest',
+    'sphinx.ext.napoleon',
     'sphinx.ext.todo',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon',
 ]
 
 # Configure `numpy` style documentation
@@ -79,14 +71,23 @@
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'default'
+
+# -- Options for autodoc -----------------------------------------------------
+
+autoclass_content = "both"
+autodoc_default_flags = ['show-inheritance', 'members', 'undoc-members']
+autodoc_member_order = 'bysource'
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+if 'READTHEDOCS' in os.environ:
+    html_theme = 'default'
+else:
+    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
@@ -113,7 +114,7 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'buzzarddoc'
+htmlhelp_basename = '%sdoc' % project
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -188,14 +189,14 @@
 epub_exclude_files = ['search.html']
 
 
-# -- Extension configuration -------------------------------------------------
+# -- Other Extensions configuration ------------------------------------------
 
-# -- Options for todo extension ----------------------------------------------
+autosummary_generate = True
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
 # -- Additional setup --------------------------------------------------------
 
 def setup(app):
-    app.add_stylesheet('theme_overrides.css')
+    app.add_stylesheet('theme_overrides.css')

docs/index.rst

@@ -4,6 +4,15 @@
 Welcome to buzzard's documentation!
 ===================================
 
+In a nutshell, :code:`buzzard` reads and writes geospatial raster and vector data.
+
+Repository is located here: https://github.com/airware/buzzard
+
+.. image:: ../img/buzzard.png
+   :alt: buzzard logo
+   :align: center
+
+.. autogenerate a title
 .. toctree::
    :maxdepth: 3
    :caption: Contents:
@@ -12,8 +21,8 @@ Welcome to buzzard's documentation!
    buzzard.algo
    buzzard.srs
 
-Indices and tables
-==================
+Indices and tables:
+-------------------
 
 * :ref:`genindex`
 * :ref:`modindex`