Clearer contribution docs & add troubleshooting page (#597)

* Expanded upon the make setup docs

* Fixed formatting & speling, added troubleshooting

* same

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

CONTRIBUTING.md

@@ -16,51 +16,64 @@ Thank you for wanting to contribute to the PyScript project!
 * [Becoming a maintainer](#becoming-a-maintainer)
 * [Trademarks](#trademarks)
 
-## Code of Conduct
+# Code of Conduct
 
 The [PyScript Code of Conduct](https://github.com/pyscript/governance/blob/main/CODE-OF-CONDUCT.md) governs the project and everyone participating in it. By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers or administrators as described in that document.
 
-## Contributing
+# Contributing
 
-### Reporting bugs
+## Reporting bugs
 
 Bugs are tracked on the [project issues page](https://github.com/pyscript/pyscript/issues). Please check if your issue has already been filed by someone else by searching the existing issues before filing a new one. Once your issue is filed, it will be triaged by another contributor or maintainer. If there are questions raised about your issue, please respond promptly.
 
-#### Creating useful issues
+## Creating useful issues
 
 * Use a clear and descriptive title.
 * Describe the specific steps that reproduce the problem with as many details as possible so that someone can verify the issue.
 * Describe the behavior you observed, and the behavior you had expected.
 * Include screenshots if they help make the issue clear.
 
-### Reporting security issues
+## Reporting security issues
 
 If you aren't confident that it is appropriate to submit a security issue using the above process, you can e-mail it to security@pyscript.net
 
-### Asking questions
+## Asking questions
 
 If you have questions about the project, using PyScript, or anything else, please ask in the [PyScript forum](https://community.anaconda.cloud/c/tech-topics/pyscript).
 
-### Setting up your environment
+# Setting up your local environment
 
-* clone the repo
+* Clone the repo using
 ```
     git clone https://github.com/pyscript/pyscript
 ```
-* cd into the main project folder
+* cd into the `pyscriptjs` folder using the line below in your terminal (if your terminal is already in pyscrpit then use **cd pyscriptjs** instead)
 ```
     cd pyscript/pyscriptjs
 ```
-* install the dependencies with npm install - make sure to use nodejs version >= 16
+* Install the dependencies with the command below
+
 ```
-    npm install
+    make setup
 ```
-* run npm run dev to build and run the dev server. This will also watch for changes and rebuild when a file is saved.
+       **NOTE**: If `make setup` gives a node/npm version required  error then go to [troubleshooting](https://github.com/pyscript/governance/blob/main/TROUBLESHOOTING.md)
+
+* You can also run the examples localy by running the command below in your terminal
+```
+    make example
+```
+* Run ***npm run dev*** to build and run the dev server. This will also watch for changes and rebuild when a file is saved.
 ```
     npm run dev
 ```
+       **NOTE**: To access your local build paste `http://localhost:8080` into your browser
 
-### Places to start
+* When you make changes locally, double check that your contribution follows the PyScript formatting rules by running `npm run lint`. Note that in this case you're looking for the errors, <u>**NOT**</u> the warnings (Unless the warning is created by a local change). If an error is found by lint you should fix it <u>**before**</u> creating a pull request
+
+
+Now that node and npm have both been updated `make setup` should work, and you can continue [setting up your environment](#setting-up-your-environment) without problems (hopefully).
+
+## Places to start
 
 If you would like to contribute to PyScript, but you aren't sure where to begin, here are some suggestions.
 
@@ -69,7 +82,7 @@ If you would like to contribute to PyScript, but you aren't sure where to begin,
 * **Look over the open pull requests.** Do you have comments or suggestions for the proposed changes? Add them.
 * **Check out the examples.** Is there a use case that would be good to have sample code for? Create an example for it.
 
-### Submitting a change
+# Submitting a change
 
 All contributions must be licensed Apache 2.0, and all files must have a copy of the boilerplate license comment (can be copied from an existing file).
 

TROUBLESHOOTING.md

@@ -0,0 +1,18 @@
+# Troubleshooting
+
+This page is meant for troubleshooting common problems with PyScript.
+
+## Table of contents:
+* [Make Setup](#make-setup)
+
+## Make setup
+
+A lot of problems related to `make setup` are related to node and npm being outdated. Once npm and node are updated, `make setup` should work. You can follow the steps on the [npm documentation](https://docs.npmjs.com/try-the-latest-stable-version-of-npm)to update npm (the update command for Linux should work for Mac as well). Once npm has been updated you can continue to the instructions to update node below.
+
+To update Node run the following commands in order (Most likely you'll be prompted for your user password, this is normal):
+
+```
+sudo npm cache clean -f
+sudo npm install -g n
+sudo n stable
+```