Commits

John Paulett  committed 67df676

Working on developer documentation

  • Participants
  • Parent commits 21eff15

Comments (0)

Files changed (6)

File docs/build.rst

-===============
-Building HORNET
-===============
-
-Prerequisites
-=============
-
-    * NetworkX_
-    * Python 2.5
-    * numpy & scipy
-    * matplotlib
-    * graphviz
-    * pygraphviz
-
-.. _NetworkX: https://networkx.lanl.gov/
-
-Building
-========
-
-.. code-block:: bash
-
-    python setup.py install
-
-Cython
-======
-
-We use Cython_ for increasing the speed of certain parts of HORNET. Our goal is
-to keep HORNET as close to the standard Python implementation, so porting
-to PyPy_ (or even Jython_ or IronPython_) would be possible in the future. To 
-build the Cython modules we use a directive in setup.py:
-
-.. code-block:: bash
-
-    python setup.py build_ext --inplace
-
-setup.py by default instructs gcc to use optimizations. We use the *.pyx* 
-extension to indicate a Cython module. To manually build a Cython file into 
-a library, use:
-
-.. code-block:: bash
-
-    cython corenetwork.pyx
-    gcc -O3 -c -fPIC -I/usr/include/python2.5/ corenetwork.c
-    gcc -shared corenetwork.o -o corenetwork.so
-    rm corenetwork.o
-
-.. _Cython: http://cython.org/
-.. _Jython: http://www.jython.org/
-.. _PyPy: http://codespeak.net/pypy/
-.. _IronPython: http://www.ironpython.com/
-
-
-Buildbot
-========
-
-https://hiplab.mc.vanderbilt.edu/buildbot/
-
-
-Source Repository
-=================
-
-The unstable, development branch is located at 
-https://hiplab.mc.vanderbilt.edu/hg/hornet-unstable/ . You can check 
-the code out with `Mercurial <http://www.selenic.com/mercurial/>`_:
-
-.. code-block:: bash
-
-    hg clone https://hiplab.mc.vanderbilt.edu/hg/hornet-unstable/ hornet
-    
-The development environment of choice is currently `Eclipse 
-<http://www.eclipse.org/>`_ with the `PyDev <http://pydev.sourceforge.net/>`_ 
-plugin.
-
-
-Documentation
-=============
-
-We use Sphinx_ for handwritten and API documentation. A Makefile is included
-to assist in building the documentation. 
-
-.. code-block:: bash
-
-    make html
-    
-For documentation coverage:
-
-.. code-block:: bash
-
-    make coverage
-
-For doctest:
-
-.. code-block:: bash
-
-    make test
-    
-.. _Sphinx: http://sphinx.pocoo.org/

File docs/develop.rst

+========================
+HORNET Developers Guide
+========================
+
+HORNET is a written in `Python <http://www.python.org>`_, a modern, high-level 
+programming language. Currently, it is targeted for Python `2.5/2.6 
+<http://www.python.org/download/>`_. It is available under the :doc:`Apache 
+License, Version 2 </license>`. 
+
+
+Source Repository
+=================
+
+The development branch is located at 
+https://hiplab.mc.vanderbilt.edu/hg/hornet-unstable/ . You can check 
+the code out with `Mercurial <http://www.selenic.com/mercurial/>`_:
+
+.. code-block:: bash
+
+    $ hg clone https://hiplab.mc.vanderbilt.edu/hg/hornet-unstable/ hornet
+    
+For more information, check out the `quick start guide 
+<http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart>`_.
+
+
+Eclipse IDE
+===========
+
+The development environment of choice is currently `Eclipse 
+<http://www.eclipse.org/>`_ with the `PyDev <http://pydev.sourceforge.net/>`_ 
+plugin.  Optionally, you can use the `MercurialEclipse 
+<http://bitbucket.org/mercurialeclipse/main/wiki/Home>`_ plugin
+to use Mercurial from within Eclipse.
+
+
+Building
+========
+
+
+
+.. code-block:: bash
+
+    $ paver build
+
+
+Style Guidelines
+=================
+
+Project Layout
+--------------
+
+ * :file:`{HORNET_HOME}`
+ 
+   * :file:`/src`
+
+     * :file:`/hornet` - Main HORNET module
+
+       * :file:`/contrib` - Included HORNET Plugins
+
+   * :file:`/tests` - Unit tests for HORNET
+
+     * :file:`/run_tests.py` - Entry point for automated testing
+
+   * :file:`/docs` - Sphinx documentation
+   * :file:`/exp` - Experimental code that may not work
+   * :file:`pavement.py` - Build script for `Paver <www.blueskyonmars.com/projects/paver/>`_
+
+Code Style
+----------
+
+In general, we follow the coding style set forth in :pep:`8`.  
+
+`David Goodger <http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html>`_,
+`Michael Foord <http://www.voidspace.org.uk/python/articles/python_style_guide.shtml>`_,
+and `Leonardo Maffi <http://www.fantascienza.net/leonardo/ar/python_best_practices.html>`_  
+have useful additional helpful points about Python style.
+
+
+Unit Testing
+------------
+
+Ensuring code quality and accuracy of computations is paramount for
+HORNET.  To this end, we strive to obtain a very high degree of test
+coverage of our code.  The main method of testing is simple `unit tests
+<http://diveintopython.org/unit_testing/index.html>`_,
+which test the code at a low level (typically at the method or function
+level).
+
+Tests are located at :file:`{HORNET_HOME}/tests`.  In general each test
+module represents the corresponding module in :file:`{HORNET_HOME}/src`.
+
+Tests general are written in the `nose <http://somethingaboutorange.com/mrl/projects/nose/>`_
+style. For example, if we have a function ``square()``:
+
+.. code-block:: python
+
+    def square(x):
+        return x * x
+
+We can write a simple test for this function:
+
+
+.. code-block:: python
+
+    def test_square():
+        assert square(4) == 16
+
+To run the entire HORNET test suite, there is a paver task:
+
+.. code-block:: bash
+
+    $ paver test
+
+
+Documentation
+-------------
+
+Since HORNET is a framework, it is important that 3rd party developers 
+be able to view complete, up-to-date documentation of how HORNET works and
+how they can extend it. 
+
+We use `Sphinx <http://sphinx.pocoo.org>`_ for handwritten and API documentation. 
+It uses `reStructured Text <http://sphinx.pocoo.org/rest.html>`_ as its markup format.  The documentation source files are
+located at :file:`{HORNET_HOME}/docs`.  Sphinx can also pull in the 
+`docstrings  <http://diveintopython.org/getting_to_know_python/documenting_functions.html>`_
+from any Python source file, thus aiding in API documentation.
+
+
+.. code-block:: bash
+
+    $ paver htmlserve
+
+Often, it is useful to include simple examples of how code should work in
+the documentation (referred to as `doctests <http://http://en.wikipedia.org/wiki/Doctest>`_.  
+To ensure that the examples in the documentation actually work, we use
+a paver task to test the examples:
+
+
+.. code-block:: bash
+
+    $ paver doctest
+
+
+Continuous Integration Server
+=============================
+
+In order to ensure that the code in the public repository is constantly
+is a healthly state, we use a continuous integration server to detect
+any code changes (i.e. pushes to the repository), build to code, and
+run the test suite.  The goal is to only push code to the repository 
+when it is in a buildable state. We currently use 
+`Hudson <https://hudson.dev.java.net>`_ at:
+
+https://hiplab.mc.vanderbilt.edu/hudson/
+

File docs/index.rst

     configuration
     ref/contrib/index
     ref/index
-    build
+    develop
     about
 
 Indices and tables

File docs/license.rst

 License
 ===============
 
-HORNET is licensed under the open-source Apache License version 2.
+HORNET is licensed under the open-source `Apache License, Version 2
+<http://www.apache.org/licenses/LICENSE-2.0>`_, Copyright 2009 
+`Vanderbilt University <http://www.vanderbilt.edu>`_.
 
 
 Apache License, Version 2.0
 from paver.easy import *
 from paver.setuputils import setup
 from setuptools import find_packages
-import sphinx
 import paver.doctools
 import sys
 import os
     #test_suite = 'nose.collector',
     #install_requires = ['matplotlib', 'numpy', 'processing', 'decorator',
     #                    'networkx', 'wxPython', 'sqlalchemy'], #'configobj', 
-    #setup_requires = ['cython', 'sphinx', 'mock', 'nose', 'coverage'],
+    setup_requires = ['sphinx', 'mock', 'nose', 'NoseXUnit', 'coverage'],
 )
 
 options(
     ),
     pylint = Bunch(
         module=['hornet']
-    )
+    ),
+    htmlserve = Bunch(
+        docsdir = './docs/.build/html/',
+        port = 8000
+    ),
 )
 
 @task
 @needs('html')
 def doctest():
     """Test the doctests in Sphinx."""
+    import sphinx
     options.order('sphinx', add_rest=True)
     paths = paver.doctools._get_paths()
     sphinxopts = ['', '-b', 'doctest', '-d', paths.doctrees, 
     """Run the test suite and output JUnit format results."""
     import run_tests
     run_tests.main(argv=['--with-nosexunit', '--enable-cover', '--source-folder='+SRC_DIR])
+
+@task
+@needs('html')
+def htmlserve():
+    import SimpleHTTPServer
+    import SocketServer
+    import os
     
+    os.chdir(options.docsdir)
+    
+    handler = SimpleHTTPServer.SimpleHTTPRequestHandler
+    httpd = SocketServer.TCPServer(('', options.port), handler)
+    
+    print 'serving at port', options.port
+    httpd.serve_forever()
 
-pass

File src/hornet/file.py

 def remove(path):
     """Deletes the file or directory specified by *path*. If it is a directory, 
     all sub-directories and files will be removed. Designed to be equivalent
-    to the unix command ``rm -rf``
+    to the unix command :command:`rm -rf`
     
     .. warning::
         This method has not been extensively tested, especially on complex