Script Documentation... it is all in the docs

03-27-2018 06:08 AM
Labels (1)
MVP Esteemed Contributor
4 1 590

Help.... Documentation

Last thing written... if ever... First thing needed.

I have been messing with formatting my code using numpy doc strings

Code documentation.... the view on the left is within the script IDE and the view on the right is what is will look like when viewing a script's help.  Fancy... fancy...

And! Not only that, your favorite Python Package Manager includes it in their python distribution so Sphinx can use it.

So here is a little 'dirr' function I wrote since dir(object) returns a messy hard to read output in any form.

Here is the documentation for the function.

def dirr(obj, colwise=True, cols=3, sub=None, prn=True):
    """A formatted dir listing of a module or function.

    Source : arraytools module in, dirr def

    Return a directory listing of a module's namespace or a part of it if the
    `sub` option is specified.  If  `prn=True`, then it is simply printed. If
    False, then the string is returned.

    - colwise : `True` or `1`, otherwise, `False` or `0`
    - cols : pick a size to suit
    - sub : sub='a' all modules beginning with `a`
    - prn : `True` for print or `False` to return output as string


    See the `inspect` module for possible additions like `isfunction`,
    'ismethod`, `ismodule`


        dirr(art, colwise=True, cols=3, sub=None, prn=True)  # all columnwise
        dirr(art, colwise=True, cols=3, sub='arr', prn=True) # just the `arr`'s

          (001)    _arr_common     arr2xyz         arr_json
          (002)    arr_pnts        arr_polygon_fc  arr_polyline_fc
          (003)    array2raster    array_fc
          (004)    array_struct    arrays_cols

The key (apparently) is indentation, back-ticks and little tricks. 

In Spyder's help documentation, it looks like this. ( More on Spyder as an IDE for your work )

You can produce whole documentation for your modules or even single 'scripts' to accompany your code.

And the function itself makes finding my own documentation easier

Sample output
# ---- by column

dirr(art, colwise=True, cols=4, sub='arr')

| dir(arraytools) ...
|    <module 'arraytools' from 'C:\\Git_Dan\\arraytools\\'>
  (001)    _arr_common     arr_pnts        array2raster    array_struct    
  (002)    arr2xyz         arr_polygon_fc  array_fc        arrays_cols     
  (003)    arr_json        arr_polyline_fc                                 

# ---- by row

dirr(art, colwise=False, cols=4, sub='arr')

| dir(arraytools) ...
|    <module 'arraytools' from 'C:\\Git_Dan\\arraytools\\'>
  (001)    _arr_common     arr2xyz         arr_json        arr_pnts        
  (002)    arr_polygon_fc  arr_polyline_fc array2raster                    
  (003)    array_fc        array_struct    arrays_cols                     

# ---- standard method

['__all__', '__args', '__art_modules__', '__art_version__', '__builtins__', 
'__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__',
 '__spec__', '_arr_common', '_center', '_centroid', '_common', '_convert',
 '_cursor_array', '_demo_frmt', '_demo_ma', '_demo_rec', '_densify_2D', '_describe',
 '_even_odd', '_extent', '_flat_', '_func', '_geo_array', '_get_shapes', '_help',
 '_id_geom_array', '_max', '_min', '_ndarray', '_new_view_', '_pad_', '_pad_even_odd',
 '_pad_nan', '_pad_zero', '_props', '_reshape_', '_split_array', '_two_arrays',
 '_unpack', '_view_', '_xy', '_xyID', '_xy_idx', 'a_filter', 'a_io', 'all_folders',
 'analysis', 'angle_2pnts', 'angle_np', 'angle_seq', 'angles_poly', 'apt', 'arc_np',
 'areas', 'arr2xyz', 'arr_json', 'arr_pnts', 'arr_polygon_fc', 'arr_polyline_fc',
 'array2raster', 'array_fc', 'array_struct', 'arrays_cols', 'azim_np', 'block',
 'block_arr', 'centers', 'centroids', 'change_arr', 'change_fld', 'circle',

.... snip‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Producing links to web links

This may be a bit much, but your documentation can also provide links to http: sites to reference specific web pages from within your documentation.  Here is an example.  The key is to provide a

  • link number ... [1]
  • a name for the link... with trailing __
  • and the actual link itself.

Web links in script documentation

**creating meshgrids from x,y data and plotting**

`2D array of values based on coordinates`__:


`2D histogram issues`__:


**distance calculations and related** .... (scipy, skikit-learn)

The **text** provides bold highlighting.  The [1] on line 6, is the first link with line 7 being the link name in back-tics and trailing __.  Line 9, with the leading __ is the actual link itself.  What is show is a snip of the whole link list shown below.

Simpler option

You might need a simpler documentation example




This consists of `< at the start and >`_. at the end with the link in between.  This yields...


Remember, documentation is important. If not for yourself, for someone else.

1 Comment
About the Author
Retired Geomatics Instructor at Carleton University. I am a forum MVP and Moderator. Current interests focus on python-based integration in GIS. See... Py... blog, my GeoNet blog...