set up ad doc

Author: AntSimi

.hgignore

@@ -6,6 +6,7 @@ syntax: glob
 *.eclipse.*
 *.idea*
 *.project*
+doc/.*
 syntax: regexp
 ^build$
 syntax: regexp

README.md

@@ -37,151 +37,3 @@ for tracking.
 
 ### Grid manipulation ###
 
-Loading grid
-```python
-from py_eddy_tracker.dataset.grid import RegularGridDataset
-grid_name, lon_name, lat_name = 'share/nrt_global_allsat_phy_l4_20190223_20190226.nc', 'longitude', 'latitude'
-h = RegularGridDataset(grid_name, lon_name, lat_name)
-```
-
-Plotting grid
-```python
-from matplotlib import pyplot as plt
-fig = plt.figure(figsize=(14, 12))
-ax = fig.add_axes([.02, .51, .9, .45])
-ax.set_title('ADT (m)')
-ax.set_ylim(-75, 75)
-ax.set_aspect('equal')
-m = h.display(ax, name='adt', vmin=-1, vmax=1)
-ax.grid(True)
-plt.colorbar(m, cax=fig.add_axes([.94, .51, .01, .45]))
-```
-
-Filtering
-```python
-h = RegularGridDataset(grid_name, lon_name, lat_name)
-h.bessel_high_filter('adt', 500, order=3)
-```
-
-Save grid
-```python
-h.write('/tmp/grid.nc')
-```
-
-Add second plot
-```python
-ax = fig.add_axes([.02, .02, .9, .45])
-ax.set_title('ADT Filtered (m)')
-ax.set_aspect('equal')
-ax.set_ylim(-75, 75)
-m = h.display(ax, name='adt', vmin=-.1, vmax=.1)
-ax.grid(True)
-plt.colorbar(m, cax=fig.add_axes([.94, .02, .01, .45]))
-fig.savefig('share/png/filter.png')
-```
-
-![signal filtering](share/png/filter.png)
-
-#### Compute spectrum and spectrum ratio on some area ####
-Load data
-```python
-raw = RegularGridDataset(grid_name, lon_name, lat_name)
-filtered = RegularGridDataset(grid_name, lon_name, lat_name)
-filtered.bessel_low_filter('adt', 150, order=3)
-
-areas = dict(
-    sud_pacific=dict(llcrnrlon=188, urcrnrlon=280, llcrnrlat=-64, urcrnrlat=-7),
-    atlantic_nord=dict(llcrnrlon=290, urcrnrlon=340, llcrnrlat=19.5, urcrnrlat=43),
-    indien_sud=dict(llcrnrlon=35, urcrnrlon=110, llcrnrlat=-49, urcrnrlat=-26),
-    )
-```
-
-Compute and display spectrum
-```python
-fig = plt.figure(figsize=(10,6))
-ax = fig.add_subplot(111)
-ax.set_title('Spectrum')
-ax.set_xlabel('km')
-for name_area, area in areas.items():
-
-    lon_spec, lat_spec = raw.spectrum_lonlat('adt', area=area)
-    mappable = ax.loglog(*lat_spec, label='lat %s raw' % name_area)[0]
-    ax.loglog(*lon_spec, label='lon %s raw' % name_area, color=mappable.get_color(), linestyle='--')
-
-    lon_spec, lat_spec = filtered.spectrum_lonlat('adt', area=area)
-    mappable = ax.loglog(*lat_spec, label='lat %s high' % name_area)[0]
-    ax.loglog(*lon_spec, label='lon %s high' % name_area, color=mappable.get_color(), linestyle='--')
-
-ax.set_xscale('log')
-ax.legend()
-ax.grid()
-fig.savefig('share/png/spectrum.png')
-```
-
-![spectrum](share/png/spectrum.png)
-
-Compute and display spectrum ratio
-```python
-fig = plt.figure(figsize=(10,6))
-ax = fig.add_subplot(111)
-ax.set_title('Spectrum ratio')
-ax.set_xlabel('km')
-for name_area, area in areas.items():
-    lon_spec, lat_spec = filtered.spectrum_lonlat('adt', area=area, ref=raw)
-    mappable = ax.plot(*lat_spec, label='lat %s high' % name_area)[0]
-    ax.plot(*lon_spec, label='lon %s high' % name_area, color=mappable.get_color(), linestyle='--')
-
-ax.set_xscale('log')
-ax.legend()
-ax.grid()
-fig.savefig('share/png/spectrum_ratio.png')
-```
-![spectrum ratio](share/png/spectrum_ratio.png)
-
-#### Run an identification on a grid ####
-
-Activate verbose
-```python
-import logging
-logging.getLogger().setLevel('DEBUG') # Values: ERROR, WARNING, INFO, DEBUG
-```
-
-Run identification
-```python
-from datetime import datetime
-h = RegularGridDataset(grid_name, lon_name, lat_name)
-h.bessel_high_filter('adt', 500, order=3)
-date = datetime(2019, 2, 23)
-a, c = h.eddy_identification(
-    'adt', 'ugos', 'vgos', # Variable to use for identification
-    date, # Date of identification
-    0.002, # step between two isolines of detection (m)
-    pixel_limit=(5, 2000), # Min and max of pixel can be include in contour
-    shape_error=55, # Error maximal of circle fitting over contour to be accepted
-    bbox_surface_min_degree=.125 ** 2, # degrees surface minimal to take in account contour
-    )
-```
-
-Plot identification
-```python
-fig = plt.figure(figsize=(15,7))
-ax = fig.add_axes([.03,.03,.94,.94])
-ax.set_title('Eddies detected -- Cyclonic(red) and Anticyclonic(blue)')
-ax.set_ylim(-75,75)
-ax.set_xlim(0,360)
-ax.set_aspect('equal')
-a.display(ax, color='b', linewidth=.5)
-c.display(ax, color='r', linewidth=.5)
-ax.grid()
-fig.savefig('share/png/eddies.png')
-```
-
-![eddies detected](share/png/eddies.png)
-
-Save identification datas
-```python
-with Dataset(date.strftime('share/Anticyclonic_%Y%m%d.nc'), 'w') as h:
-    a.to_netcdf(h)
-with Dataset(date.strftime('share/Cyclonic_%Y%m%d.nc'), 'w') as h:
-    c.to_netcdf(h)
-```

doc/autodoc/eddy_feature.rst

@@ -0,0 +1,8 @@
+Eddy Features
+=============
+
+.. automodule:: py_eddy_tracker.eddy_feature
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

doc/autodoc/featured_tracking.rst

@@ -0,0 +1,7 @@
+Featured tracking
+=================
+
+.. automodule:: py_eddy_tracker.featured_tracking.old_tracker_reference
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/autodoc/grid.rst

@@ -0,0 +1,8 @@
+Grid
+====
+
+.. automodule:: py_eddy_tracker.dataset.grid
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

doc/autodoc/observations.rst

@@ -0,0 +1,8 @@
+Observations
+============
+
+.. automodule:: py_eddy_tracker.observations
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

doc/autodoc/poly.rst

@@ -0,0 +1,8 @@
+Polygon function
+================
+
+.. automodule:: py_eddy_tracker.poly
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

doc/conf.py

@@ -112,15 +112,16 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx-rtd-theme'
+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
 # documentation.
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -131,7 +132,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = '../share/png/logo.png'
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

doc/grid_identification.rst

@@ -0,0 +1,56 @@
+=====================
+Eddies identification
+=====================
+
+Run an identification on a grid
+*******************************
+
+Activate verbose
+
+.. code-block:: python
+
+    import logging
+    logging.getLogger().setLevel('DEBUG') # Values: ERROR, WARNING, INFO, DEBUG
+
+Run identification
+
+.. code-block:: python
+
+    from datetime import datetime
+    h = RegularGridDataset(grid_name, lon_name, lat_name)
+    h.bessel_high_filter('adt', 500, order=3)
+    date = datetime(2019, 2, 23)
+    a, c = h.eddy_identification(
+        'adt', 'ugos', 'vgos', # Variable to use for identification
+        date, # Date of identification
+        0.002, # step between two isolines of detection (m)
+        pixel_limit=(5, 2000), # Min and max of pixel can be include in contour
+        shape_error=55, # Error maximal of circle fitting over contour to be accepted
+        bbox_surface_min_degree=.125 ** 2, # degrees surface minimal to take in account contour
+        )
+
+Plot identification
+
+.. code-block:: python
+
+    fig = plt.figure(figsize=(15,7))
+    ax = fig.add_axes([.03,.03,.94,.94])
+    ax.set_title('Eddies detected -- Cyclonic(red) and Anticyclonic(blue)')
+    ax.set_ylim(-75,75)
+    ax.set_xlim(0,360)
+    ax.set_aspect('equal')
+    a.display(ax, color='b', linewidth=.5)
+    c.display(ax, color='r', linewidth=.5)
+    ax.grid()
+    fig.savefig('share/png/eddies.png')
+
+.. image:: ../share/png/eddies.png
+
+Save identification datas
+
+.. code-block:: python
+
+    with Dataset(date.strftime('share/Anticyclonic_%Y%m%d.nc'), 'w') as h:
+        a.to_netcdf(h)
+    with Dataset(date.strftime('share/Cyclonic_%Y%m%d.nc'), 'w') as h:
+        c.to_netcdf(h)

doc/grid_load_display.rst

@@ -0,0 +1,56 @@
+===========================
+Load, Display and Filtering
+===========================
+
+Loading grid
+
+.. code-block:: python
+
+    from py_eddy_tracker.dataset.grid import RegularGridDataset
+    grid_name, lon_name, lat_name = 'share/nrt_global_allsat_phy_l4_20190223_20190226.nc', 'longitude', 'latitude'
+    h = RegularGridDataset(grid_name, lon_name, lat_name)
+
+Plotting grid
+
+.. code-block:: python
+
+    from matplotlib import pyplot as plt
+    fig = plt.figure(figsize=(14, 12))
+    ax = fig.add_axes([.02, .51, .9, .45])
+    ax.set_title('ADT (m)')
+    ax.set_ylim(-75, 75)
+    ax.set_aspect('equal')
+    m = h.display(ax, name='adt', vmin=-1, vmax=1)
+    ax.grid(True)
+    plt.colorbar(m, cax=fig.add_axes([.94, .51, .01, .45]))
+
+
+Filtering
+
+.. code-block:: python
+
+    h = RegularGridDataset(grid_name, lon_name, lat_name)
+    h.bessel_high_filter('adt', 500, order=3)
+
+
+Save grid
+
+.. code-block:: python
+
+    h.write('/tmp/grid.nc')
+
+
+Add second plot
+
+.. code-block:: python
+
+    ax = fig.add_axes([.02, .02, .9, .45])
+    ax.set_title('ADT Filtered (m)')
+    ax.set_aspect('equal')
+    ax.set_ylim(-75, 75)
+    m = h.display(ax, name='adt', vmin=-.1, vmax=.1)
+    ax.grid(True)
+    plt.colorbar(m, cax=fig.add_axes([.94, .02, .01, .45]))
+    fig.savefig('share/png/filter.png')
+
+.. image:: ../share/png/filter.png