howto_document_code.txt

How I (try) To Document ... Overview
-------------------------------------

I have divided this repository into algorithms, snippets and utilities 
subdirectories. 

I try for slightly different levels of documentation for each type of 
contribution. More specific information and examples for each are listed 
in the 'howto_' and 'example_' files in each directory. But, here are 
some general principles I'm trying to follow.

algos - Shared code that provides working algorithms.
    - Document each module at both the MODULE and FUNCTION level.
    - Embed a test using " if __name__ == "__main__": "
    - Embed a simple data set on which to run the test, otherwise document 
      where to get the test data.
    - Best case, embed a test and data AND a comparison to known results 
      to demonstrate that code is working correctly
        
snips - Contains example code about how to do something. These do not 
        necessarily have to be fully working example.
    - Thoroughly document each MODULE within each function,
      especially if it is non-working code.
    - If possible, embed a test using " if __name__ == "__main__": "
        
utils - For shared code that provided working utility functions.
    - These are 'non-algos' modules/functions that could be of use to users.
        - example: data conversion, plotting, etc.
    - Please document each module at both the MODULE and FUNCTION level..    
    - Embed a test using " if __name__ == "__main__": "
    - Embed a simple data set on which to run the test, otherwise document 
      where to get the test data.