Getting Started with PySAL

For Users

Users can begin the journey with PySAL by exploring the courses, workshops, tutorials, and presentations:

For developers

Developers for PySAL and its submodules are expected to follow Github Standard Operating Procedures

In order for packages to be included into pysal as a submodule, it must follow the Submodule Contract below:

Submodule Contract

Python version

  • must support python 3.

Structure

  • must be organized in the same hierarchy as the submodule template. Note specifically:
  • tests inside of the package, rather than outside.
  • data within tests is only referred to by tests, and is used as comparison output for testing.
  • notebooks is outside of the package.

Documentation & testing

  • must have unittesting on user-facing classes (those exposed by the API)
  • must have docstrings for all user-facing functions
  • must run these tests nightly (using either nightli.es or CRON jobs on travis)
  • must have three notebooks in notebooks
  • must host documentation (see the next section for guidelines of building a doc website)

Code Standards

  • must refer to data in lib.examples
  • must only have module-level imports that the package supports in its requirements.txt
  • must write from submodule import function instead of import submodule.function if it wants to use a function of a PySAL submodule
  • all function-level imports (those made at the top of a function) must be decorated with the requires decorator or raises an explicit exception (i.e. raise ImportError(‘this function requires `PACKAGE, which is not installed.’)) if its requirements are not met.
  • must be pep8 compliant. We recommend using autopep8 to automatically convert non-compliant code, and using flake8 thereafter.

Building a sphinx doc website for the submodule

Building documentation for Python docstrings

The following Sphinx extensions will be used for parsing docstrings and semi-automatically pulling in documentation from docstrings:

Bibliography and cross-reference

We leverage the functionality provided by the Sphinx extension for BibTeX style citations sphinxcontrib-bibtex to quickly and conveniently build a reference list which could be for those cited in a particular webpage or a bunch of webpages by feeding with a bib file.