Docs/pycharm setup (#1169)

* Just some notes from getting my dev environnent set up again.

* fix readme link

* fixing black configuration.

* Black config settings in pre-commit.

* Update README.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update README.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update spiffworkflow-backend/docs/pycharm.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update spiffworkflow-backend/docs/pycharm.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update spiffworkflow-backend/docs/pycharm.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update spiffworkflow-backend/docs/pycharm.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

.pre-commit-config.yaml

@@ -8,6 +8,7 @@ repos:
         language: system
         files: ^spiffworkflow-backend/
         types: [python]
+        line-length: 130
         require_serial: true
         # exclude: ^migrations/
         exclude: "/migrations/"

README.md

@@ -21,14 +21,21 @@ There are three prerequisites for non-docker local development:
 3. mysql - the app also supports postgres. and sqlite, if you are talking local dev).
 
 When these are installed, you are ready for:
-
+```bash
     cd spiffworkflow-backend
     poetry install
     ./bin/recreate_db clean
     ./bin/run_server_locally
+```
 
-On a Mac, port 7000 (used by the backend) might be hijacked by Airplay. For those who upgraded to MacOS 12.1 and are running everything locally, your AirPlay receiver may have started on Port 7000 and your server (which uses port 7000 by default) may fail due to this port already being used. You can disable this port in System Preferences > Sharing > AirPlay receiver.
+**Mac Port Errors**: On a Mac, port 7000 (used by the backend) might be hijacked by Airplay. For those who upgraded to macOS 12.1 and are running everything locally, your AirPlay receiver may have started on Port 7000 and your server (which uses port 7000 by default) may fail due to this port already being used. You can disable this port in System Preferences > Sharing > AirPlay receiver.
 
+**Poetry Install Errors**: If you encounter errors with the Poetry install, please note that MySQL and PostgreSQL may require certain packages exist on your system prior to installing these libraries. 
+Please see the [PyPi mysqlclient instructions](https://pypi.org/project/mysqlclient/) and the pre-requisites for the [Postgres psycopq2 adapter](https://www.psycopg.org/docs/install.html#prerequisites) Following the  instructions here carefully will assure your OS has the right dependencies installed.
+Correct these, and rerun the above commands.
+
+**Using PyCharm?** If you would like to run or debug your project within an editor like PyCharm please see
+[These directions for PyCharm Setup](spiffworkflow-backend/docs/pycharm.md).
 
 ## Keycloak Setup
 

pyproject.toml

@@ -33,3 +33,6 @@ pyupgrade = "^3.1.0"
 
 [tool.poetry.group.dev.dependencies]
 tomli = "^2.0.1"
+
+[tool.black]
+line-length = 130

spiffworkflow-backend/README.rst

@@ -34,6 +34,12 @@ See detailed instructions at the root of spiff-arena, but:
 
    $ poetry install
 
+NOTE: Mysql and Postgres may require special binary files exist on your system prior
+to installing these libraries. Please see the `PyPi mysqlclient instructions`_
+and the pre-requisites for the `Postgres psycopq2 adapter`_ Following the
+instructions here carefully will assure your OS has the right dependencies
+installed.
+
 * Setup the database - uses mysql and assumes server is running by default:
 
 .. code:: console
@@ -79,3 +85,5 @@ This project was generated from `@cjolowicz`_'s `Hypermodern Python Cookiecutter
 .. _Hypermodern Python Cookiecutter: https://github.com/cjolowicz/cookiecutter-hypermodern-python
 .. _file an issue: https://github.com/sartography/spiffworkflow-arena/issues
 .. github-only
+.. _PyPi mysqlclient instructions: https://pypi.org/project/mysqlclient/
+.. _Postgres psycopq2 adapter: https://www.psycopg.org/docs/install.html#prerequisites

spiffworkflow-backend/docs/pycharm.md

@@ -0,0 +1,54 @@
+# PyCharm Setup Instructions
+
+## Pre-Requisites
+* Before starting, be sure you can run bin/run_server_locally script successfully.
+This will prove that your libraries are properly configured.
+* Checkout a git repository with sample process models such as our [Sample Process Models](https://github.com/sartography/sample-process-models)
+
+
+## Step 1 - Python Interpreter
+In the settings, ensure that you have configured your Python interpreter to use the poetry environment you have created.
+
+## Step 2 - Configuration Settings
+Create a config.py file in the src/instance directory, with the following base settings
+```python
+FLASK_SESSION_SECRET_KEY="[PUT SOME RANDOM STUFF HERE]"
+SPIFFWORKFLOW_BACKEND_APPLICATION_ROOT="/"
+SPIFFWORKFLOW_BACKEND_BPMN_SPEC_ABSOLUTE_DIR="[FULL PATH TO SAMPLE PROCESS MODEL GIT CLONE]"
+
+# This will configure your application to use a built in login rather than
+# relying on keycloak etc...
+SPIFFWORKFLOW_BACKEND_AUTH_CONFIGS = [
+    {
+    "identifier":"default",
+    "label":"internal openid",
+    "uri":"http://localhost:7000/openid",
+    "client_id":"spiffworkflow-backend",
+    "client_secret":"JXeQExm0JhQPLumgHtIIqf52bDalHz0q"
+    }
+]
+
+# You can modify the permissions by creating your owm permissions file and setting it here.  See [example.yml](../src/spiffworkflow_backend/config/permissions/example.yml)
+SPIFFWORKFLOW_BACKEND_PERMISSIONS_FILE_NAME="example.yml"
+```
+
+
+Checkout [the default.py config file](./src/spiffworkflow_backend/config/default.py) for more options you can specify here as needed.
+
+## Step 3 - Run Configuration
+
+Configure your Run configuration with the following settings:
+* select Flask Server as the run type
+* set the target to: spiffworkflow_backend
+* set the port to 7000 (-p 7000)
+* ![alt text](pycharm_config.png "PyCharm Run Configuration")
+* ![alt text](pycharm_config.png "PYCharm Run Configration")
+
+
+## Step 4 - Code Formatting
+
+We are using [Black](https://black.readthedocs.io/en/stable/) for code formatting.
+To avoid the madness of having Black enforce one style, and your editor enforcing another, you should follow [the directions outlined here](https://black.readthedocs.io/en/stable/integrations/editors.html#pycharm-intellij-idea).
+
+
+Start it up using the play / debug buttons.~~

spiffworkflow-backend/pyproject.toml

@@ -238,6 +238,10 @@ disable = [
     "fixit.rules:CompareSingletonPrimitivesByIs",
 ]
 
+[tool.black]
+line-length = 130
+
+
 [build-system]
 requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"

spiffworkflow-frontend/package-lock.json

@@ -92,7 +92,7 @@
         "ts-migrate": "^0.1.30"
       }
     },
-    "../../bpmn-js-spiffworkflow": {
+    "../bpmn-js-spiffworkflow": {
       "version": "0.0.8",
       "extraneous": true,
       "license": "MIT",