# 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.