Add development section to our docs (#920)

docs/development/deprecation-cycle.md

@@ -0,0 +1,30 @@
+# Deprecation Cycle
+
+Pyscript is under heavy development, which means that some things may change, and some features might need to be deprecated so you can use different alternative implementations.
+
+This page describes the deprecation cycle for pyscript.
+
+## Deprecation Steps
+
+1. Remove usage of deprecated features from all examples.
+2. Add warnings to all elements/features marked for deprecation.
+3. Release a new version of pyscript with the deprecation warnings.
+4. Next release, remove the deprecated features.
+
+## Deprecation Warnings
+
+Deprecation warnings are added to the codebase using the `showWarning` function from the `pyscriptjs.utils` module.
+
+This function creates a warning banner on the page if any of the deprecated features was used. You can use HTML to write the message; ideally, you should provide an alternative to the deprecated feature.
+
+### Example
+
+```js
+import {showWarning} from './utils'
+
+showWarning(`
+    <p>
+        The <code>py-deprecated</code> tag is deprecated. Please use the <code>py-actual</code> tag instead. Please refer to <a href="#">this documentation page</a> for more information.
+    </p>
+`)
+```

docs/development/developing.md

@@ -0,0 +1,54 @@
+# Developing Process
+
+This document is intended to help you get started developing for pyscript, it assumes that you have [setup your development environment](setting-up-environment.md).
+
+* First, make sure you are using the latest version of the pyscript main branch
+
+```
+git pull upstream main
+```
+
+* Update your fork with the latest changes
+
+```
+git push origin main
+```
+
+* Activate the conda environment (this environment will contain all the necessary dependencies)
+
+```
+conda activate pyscriptjs/env/
+```
+       **NOTE**: We are assuming you are in the root folder. If you are in the pyscriptjs you can run `conda activate env/` instead.
+
+* Install pre-commit (you only need to do this once)
+
+```
+pre-commit install
+```
+       **NOTE**: On first run, pre-commit installs a bunch of hooks that will be run when you commit changes to your branch - this will make sure that your code is following our style (it will also lint your code automatically).
+
+* Create a branch for the issue that you want to work on
+
+```
+git checkout -b <your branch name>
+```
+
+* Work on your change
+
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; **NOTE**: If you are working on a python file, you may encounter linting issues when pre-commit runs. Pyscript uses [black](https://black.readthedocs.io/en/stable/) to fix any linting problems automatically. All you need to do is add the changes again and commit using your previous commit message (the previous one that failed didn't complete due to black formatting files).
+
+* Run tests before pushing the changes
+
+```
+make tests
+```
+
+* 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
+
+
+## Rebasing changes
+
+Sometimes you might be asked to rebase main into your branch. Please refer to this [section on git rebase from GitHub docs](https://docs.github.com/en/get-started/using-git/about-git-rebase).
+
+If you need help with anything, feel free to reach out and ask for help!

docs/development/index.md

@@ -0,0 +1,12 @@
+# Development
+
+This section contains various topics related to pyscript development.
+
+```{toctree}
+---
+maxdepth: 1
+---
+setting-up-environment
+deprecation-cycle
+developing
+```

docs/development/setting-up-environment.md

@@ -0,0 +1,69 @@
+# Setting up your development environment
+
+* Fork the repository - [quicklink](https://github.com/pyscript/pyscript/fork)
+
+* Clone your fork of the project
+
+```
+git clone https://github.com/<your username>/pyscript
+```
+
+* Add the original project as your upstream (this will allow you to pull the latest changes)
+
+```sh
+git remote add upstream git@github.com:pyscript/pyscript.git
+```
+
+* cd into the `pyscriptjs` folder using the line below in your terminal (if your terminal is already in pyscript then use **cd pyscriptjs** instead)
+
+```
+cd pyscript/pyscriptjs
+```
+
+* Install the dependencies with the command below (you must have node >=16)
+
+```
+make setup
+```
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; **NOTE**: If `make setup` gives a node/npm version required  error then go to [troubleshooting](https://github.com/pyscript/pyscript/blob/main/TROUBLESHOOTING.md)
+
+* You can also run the examples locally by running the command below in your terminal
+
+```
+make examples
+```
+
+* 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
+```
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; **NOTE**: To access your local build paste `http://localhost:8080` into your browser
+
+
+Now that node and npm have both been updated `make setup` should work, and you can continue [setting up your local environment](setting-up-environment.md) without problems (hopefully).
+
+
+## Setting up and building the docs
+
+To build the documentation locally first make sure you are in the `docs` directory.
+
+You'll need `make` and `conda` installed in your machine. The rest of the environment should be automatically download and created for you once you use the command:
+
+```
+make setup
+```
+
+Use `conda activate $environment_name` to activate your environment.
+
+To add new information to the documentation make sure you conform with PyScript's code of conduct and with the general principles of Diataxis. Don't worry about reading too much on it, just do your best to keep your contributions on the correct axis.
+
+Write your documentation files using [Markedly Structured Text](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html), which is very similar to vanilla Markdown but with some addons to create the documentation infrastructure.
+
+Once done, initialize a server to check your work:
+
+```
+make livehtml
+```
+
+Visible here: [http://127.0.0.1:8000](http://127.0.0.1:8000)