<commit_before>****************************
Building PySAL Documentation
****************************
 
PySAL documentation is built using `Sphinx <http://pypi.python.org/pypi/Sphinx/1.0.3>`_.
We also use the `numpydoc <http://pypi.python.org/pypi/numpydoc/0.3.1>`_ extension to Sphinx which customizes the markup
of the docstrings of the PySAL modules. 
For those intent on building the documentation at this time, due to changes
brought about by upgrading to Sphinx v1.0.3, you will need SciPy's latest
numpydoc extension. Download their source code. In the doc directory you will
find a setup.py file inside the sphinxext directory. That setup.py will install
just the latest Sphinx extensions into your current python site-packages
directory. It is advised that you first remove any numpydoc folders in
site-packages first, upgrade your Sphinx version, then install the new numpydoc
extension.

The source for the docs is in `trunk/doc`. Building the documentation is
done as follows (assuming
sphinx and numpydoc are already installed)::

        serge@think:~/Research/p/PySAL/src/google/trunk/doc$ ls
        build  Makefile  source

        serge@think:~/Research/p/PySAL/src/google/trunk/doc$ make clean;make html


To see the results in a browser open `build/html/index.html`. To make
changes, edit (or add) the relevant files in `source` and rebuild the
docs. Consult the `Sphinx markup guide <http://sphinx.pocoo.org/contents.html>`_ for details on the syntax and structure of the files in `source`.

Once you are happy with your changes, check-in the `source` files, do not
add or check-in files under  `build` since they are dynamically built.


Changes added to the `svn repository <http://code.google.com/p/pysal/>`_
will be propogated to `pysal.org <http://pysal.org>`_ on a daily basis.


Issues
======

If you run into the following error::

	Exception occurred:
	 File
	 "/Library/Python/2.6/site-packages/numpydoc-0.3.1-py2.6.egg/numpydoc/numpydoc.py",
	 line 136, in get_directive
	    raise RuntimeError("No directive named '%s' found" % name)
	    RuntimeError: No directive named 'function' found

A fix is to do the following::

	1. Upgrade sphinx to 1.0.4.

	    pip install -U sphinx

    2. Upgrade numpydoc

        pip install -U numpydoc

	3. Optionally: Upgrade to the latest numpydoc extension from the scipy source:
                svn co http://svn.scipy.org/svn/scipy/trunk scipy
		cd scipy/doc/sphinxext/
		svn update
		python setup.py install

We've added the Sphinx extension 'viewcode.' Displaying the option to view code
inline requires at least one properly formatted docstring in your module.<commit_msg>Mods and cosmetic changes to sphinx and numpydoc upgrade instructions.<commit_after>****************************
Building PySAL Documentation
****************************
 
PySAL documentation is built using `Sphinx <http://pypi.python.org/pypi/Sphinx/1.0.3>`_.
We also use the `numpydoc <http://pypi.python.org/pypi/numpydoc/0.3.1>`_ extension to Sphinx which customizes the markup
of the docstrings of the PySAL modules. 
For those intent on building the documentation at this time, due to changes
brought about by upgrading to Sphinx v1.0.3, you will need SciPy's latest
numpydoc extension. Download their source code. In the doc directory you will
find a setup.py file inside the sphinxext directory. That setup.py will install
just the latest Sphinx extensions into your current python site-packages
directory. It is advised that you first remove any numpydoc folders in
site-packages first, upgrade your Sphinx version, then install the new numpydoc
extension.

The source for the docs is in `trunk/doc`. Building the documentation is
done as follows (assuming
sphinx and numpydoc are already installed)::

        serge@think:~/Research/p/PySAL/src/google/trunk/doc$ ls
        build  Makefile  source

        serge@think:~/Research/p/PySAL/src/google/trunk/doc$ make clean;make html


To see the results in a browser open `build/html/index.html`. To make
changes, edit (or add) the relevant files in `source` and rebuild the
docs. Consult the `Sphinx markup guide <http://sphinx.pocoo.org/contents.html>`_ for details on the syntax and structure of the files in `source`.

Once you are happy with your changes, check-in the `source` files, do not
add or check-in files under  `build` since they are dynamically built.


Changes added to the `svn repository <http://code.google.com/p/pysal/>`_
will be propogated to `pysal.org <http://pysal.org>`_ on a daily basis.


Issues
======

If you run into the following error::

	Exception occurred:
	 File
	 "/Library/Python/2.6/site-packages/numpydoc-0.3.1-py2.6.egg/numpydoc/numpydoc.py",
	 line 136, in get_directive
	    raise RuntimeError("No directive named '%s' found" % name)
	    RuntimeError: No directive named 'function' found

A fix is to do the following:

    1. Upgrade sphinx to 1.0.4::

        pip install -U sphinx

    2. Upgrade to the latest numpydoc extension from the Python Package Index::

        pip install -U numpydoc


We've added the Sphinx extension 'viewcode.' Displaying the option to view code
inline requires at least one properly formatted docstring in your module.
{'fraction_non_alphanumeric': 0.0983858570330515, 'fraction_numerical': 0.009415833973866257, 'mean_word_length': 3.915014164305949, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2747135', 'n_tokens_mistral': 1659, 'n_tokens_neox': 1505, 'n_words': 646}