Contributing to polaris-studio

Contributing to polaris-studio#

As of June 2024, this package is tested in Python 3.10 and 3.11, but it should also work properly on version 3.12.

Modifying the software#

As the software has the goal of implementing the Polaris Network Data Model, while also implementing a series of procedures for network upgrade (to newer data model versions), consistency checking and import from other formats.

Since the version of network data model is a particularly important aspect of any version of this software, below we separate the changes to the software that implement such changes, from those targeting analysis and general data manipulation.

Changing the network data model#

We understand as changes to the data model, any change that is required for a new version of Polaris. That includes, but is not limited to, the following:

  • New project tables

  • New fields to tables

When performing these changes, a series of items need to be observed, as we suggest you to use the following as a checklist when doing your own changes or reviewing code written by other team members.

  • Is there an opportunity to write database triggers to enforce consistency of this new field/table. Have I written them?

  • Was the documentation updated to reflect these changes?

  • Have I written tests to cover these new tables/fields, including triggers?

  • Have I written the scripts to automate the update of previous version networks’ updates

  • Have all unit tests passed?

Fixing bugs and adding features#

When fixing bugs and adding features, the checklist above can also be used prior to release. In the case of bugs and special cases, it is recommended that new unit tests are written to prevent similar issues from happening in the future.

Package documentation#

The documentation is written in Restructured Text, and it lives in the docs/source, accessible from the root directory of you project.

Documenting table declarations#

The auto-generated pages for table present in the model can carry documentation over from the SQL files where they are includes.

The basic principle is that any line beginning with –@ in the SQL file will be copied to the auto-generated documentation as raw restructured text, so formatting such as bold and italic or even bullet points are possible and welcome.

One example is the documentation for the Link table, which looks like this in the raw SQL file

SQL file documentation

And it is rendered like this

Rendered SQL documentation

Setting up your dev environment#

As it goes with most Python packages, it is recommend that you use a dedicated development virtual environment. It is also assumed that you are using PyCharm.

Non-Windows#

./ci.sh setup_dev

Windows#

Make sure to clone this repository and run the following from within that cloned repo using an elevated command prompt.

If you already have Python 3.11 installed machine, you can proceed as follows:

python -m pip install pipenv
virtualenv .venv # Only if you want to save the virtual environment in the same folder
python -m pipenv install --dev
python -m pipenv run pre-commit-install

If not, Python 3.11 needs to be installed, and the following instructions assume you are using Chocolatey as a package manager.

cinst python3 --version 3.11.9
cinst python

set PATH=C:\Python311;%PATH%
python -m pip install pipenv
virtualenv .venv # Only if you want have the virtual env in the dev folder
python -m pipenv install --dev
python -m pipenv run pre-commit-install

Manually building the documentation#

Building the documentation is a two part process, as the the documentation for the project tables has been automated.

The first step is to create the rst (restructured text) files corresponding to each and every project table. That can be achieved by simply running the following from the root of your project (considering you have the virtual environment activated).

python -m table_documentation.py

If you find problems running the above command line, try running the table_documentation.py file direcly in PyCharm.

After that has finished running (should take only 1 to 2 seconds), the following should be run also in the command line

cd docs
make html

The output documentation will be inside your project’s folder under the subfolder

./docs/build/html/.

Releases#

PolarisNetwork is not yet available in the Python Package Index (pypi).

Finally#

A LOT of the structure around the documentation was borrowed (copied) from Aequilibrae.

Contents