Run docs locally and add Deploy Previews through Netlify (#459)

* feat: add @openzeppelin/docs-utils to work locally with documentation

* docs: update CONTRIBUTING guide with documetation setup

* docs: add missing section to CONTRIBUTING

* feat: fix markdown linter report

* refactor: remove unnecesary install from tox.ini

* feat(docs): add netlify.toml to integrate deploy previews

* refactor: remove watching directory

* fix(contributing): resolve comments from review

* trigger build

* refactor: set relative call for oz-docs script in package.json

* docs: fix typo in CONTRIBUTING.md

Co-authored-by: Francisco Giordano <frangio.1@gmail.com>

.gitignore

@@ -132,3 +132,9 @@ dmypy.json
 
 # nile
 *node.json*
+
+# node
+**/node_modules/
+
+# docs
+docs/build/

CONTRIBUTING.md

@@ -11,15 +11,15 @@ Also, consider that snake case is used for Cairo development in general due to i
 And make sure to always include tests and documentation for the new developments. Please consider the following conventions:
 
 - Naming
-  - libraries should be named `library.cairo`, e.g. `erc20/library.cairo`
-  - contracts should be PascalCased i.e. `MyContract.cairo`
-  - interfaces should be prefixed with an `I`, as in `IAccount.cairo`
-  - test modules should begin with `test_` followed by the contract name i.e. `test_MyContract.py`
+  - Libraries should be named `library.cairo`, e.g. `erc20/library.cairo`
+  - Contracts should be PascalCased i.e. `MyContract.cairo`
+  - Interfaces should be prefixed with an `I`, as in `IAccount.cairo`
+  - Test modules should begin with `test_` followed by the contract name i.e. `test_MyContract.py`
 
 - Structure
-  - libraries should cede their names to their parent directory and are named `library.cairo` instead
-  - interfaces should be alongside the library that the interface defines
-  - preset contracts should be within a `presets` directory of the library to which they are a preset
+  - Libraries should cede their names to their parent directory and are named `library.cairo` instead
+  - Interfaces should be alongside the library that the interface defines
+  - Preset contracts should be within a `presets` directory of the library to which they are a preset
   - Here are example paths:
     - `openzeppelin.token.erc20.library`
     - `openzeppelin.token.erc20.IERC20`
@@ -53,26 +53,31 @@ As a contributor, you are expected to fork this repository, work on your own for
 
     > NOTE: The directory `cairo-contracts` represents your fork's local copy.
 
-2. Branch out from `main` into `fix/some-bug-#123`:
+2. Branch out from `main` into `fix/some-bug-short-description-#123` (ex: `fix/typos-in-docs-#123`):
 
     (Postfixing #123 will associate your PR with the issue #123 and make everyone's life easier =D)
 
     ```sh
-    git checkout -b fix/some-bug-#123
+    git checkout -b fix/some-bug-short-description-#123
     ```
 
-3. Make your changes, add your files, commit, and push to your fork.
+3. Make your changes, add your files, update documentation ([see Documentation section](#documentation)), commit, and push to your fork.
 
     ```sh
     git add SomeFile.js
-    git commit "Fix some bug #123"
-    git push origin fix/some-bug-#123
+    git commit "Fix some bug short description #123"
+    git push origin fix/some-bug-short-description-#123
     ```
 
-4. Run tests, linter, etc. This can be done by running local continuous integration and make sure it passes.
+4. Run tests, linter, etc. This can be done by running local continuous integration and make sure it passes. We recommend to use a [python virtual environment](https://docs.python.org/3/tutorial/venv.html).
 
     ```bash
+    # install tox from testing dependencies
+    pip install .[testing] # '.[testing]' in zsh
+
+    # run tests
     tox
+
     # stop the build if there are Markdown documentation errors
     tox -e lint
     ```
@@ -86,6 +91,24 @@ As a contributor, you are expected to fork this repository, work on your own for
 
     *IMPORTANT* Please pay attention to the maintainer's feedback, since its a necessary step to keep up with the standards OpenZeppelin Contracts attains to.
 
+## Documentation
+
+Before submitting the PR, you must update the corresponding documentation entries in the docs folder. In the future we may use something similar to solidity-docgen to automatically generate docs, but for now we are updating .adoc entries manually.
+
+If you want to run the documentation UI locally:
+
+1. Change directory into docs inside the project and run npm install.
+
+    ```bash
+    cd docs && npm i
+    ```
+
+2. Build the docs and run the local server (default to localhost:8080). This will watch for changes in the docs/module folder, and update the UI accordingly.
+
+    ```bash
+    npm run docs:watch
+    ```
+
 ## All set
 
 If you have any questions, feel free to post them to github.com/OpenZeppelin/cairo-contracts/issues.