Merge pull request #148 from paulosgf/updaterst

Documentation - update the contributing guide - Sync *.rst files on m…

README.md

@@ -284,7 +284,7 @@ if message received == .hi:
 - don't forget to add your country flag here after accepted PR. i'll have to hunt it down on your profile if not.
 - make sure to follow PEP8
 
-**about PR**
+**About PR**
 
 first clone the project
 
@@ -298,12 +298,34 @@ cd into the project
 cd honeybot
 ```
 
+create a virtualenv to work with different python \ libs versions
+
+```
+python -m venv venv
+source venv/bin/activate
+```
+
+install the tools needed to make the constraint checks
+
+```
+pip install black isort bandit pre-commit
+pre-commit install
+```
+
 different changes to different files. for example, someone making a weather plugin first he creates a new branch
 
 ```
 git checkout -b "weather-plugin"
 ```
 
+test if all files are well formatted, complying with style and security rules, before send the PR
+
+```
+black --check --verbose --config ./pyproject.toml src/honeybot/plugins/downloaded/weather/main.py
+isort --check-only --settings-path ./pyproject.toml src/honeybot/plugins/downloaded/weather/main.py
+bandit -ll -c ./pyproject.toml -r src/honeybot/plugins/downloaded/weather/main.py 
+```
+
 then he commits
 
 ```

docs/source/How_Tos/contributing.rst

@@ -19,12 +19,35 @@ cd into the project
 
    cd honeybot
 
+create a virtualenv to work with different python \ libs versions
+
+.. code-block::
+   
+   python -m venv venv
+   source venv/bin/activate
+
+install the tools needed to make the constraint checks
+
+.. code-block::
+
+   pip install black isort bandit pre-commit
+   pre-commit install
+
 different changes to different files. for example, someone making a weather plugin first he creates a new branch
 
 .. code-block::
 
    git checkout -b "weather-plugin"
 
+test if all files are well formatted, complying with style and security rules, before send the PR
+
+.. code-block::
+
+    black --check --verbose --config ./pyproject.toml src/honeybot/plugins/downloaded/weather/main.py
+    isort --check-only --settings-path ./pyproject.toml src/honeybot/plugins/downloaded/weather/main.py
+    bandit -ll -c ./pyproject.toml -r src/honeybot/plugins/downloaded/weather/main.py     
+
+
 then he commits
 
 .. code-block::

docs/source/How_Tos/documentation.rst

@@ -2,7 +2,7 @@
 Setting up Documentation
 *************************
 
-This How To focuses on setting up Sphinx in order to edit the HoneyBot documentation.
+This How To focuses on setting up **Sphinx** in order to edit the HoneyBot documentation.
 You *don't* need to do this if you're simply adding a plugin.
 If you should have **any** questions feel free to ask on our discord_!
 
@@ -15,29 +15,70 @@ Requirements
 
 To generate the documentation you will need to have sphinx installed,
 click here_ for a quick installation guide. **Make sure you've installed the
-python 3 (new) version of sphinx!**.
+python 3 (new) version of sphinx and Read The Docs theme!**.
+
+**'pip install sphinx sphinx_rtd_theme'**.
+
 There's no need to set up this tool with **'sphinx-quickstart'** command, once there is a configuration already.
 
-Furthermore you'll need to have the **master** branch cloned from honeybot
-repo and a new branch from this master clone.
+Create a fork of our honeybot project and clone this:
+
+**'git clone https://github.com/<YOU>/honeybot.git'**
+
 Then change the path `honeybot/docs/source/`_ and edit the *.rst* files there.
 These *.rst* files they are too on following paths: `honeybot/docs/source/How_Tos/`_ and `honeybot/docs/source/Plugins/`_.
 
+Next you’ll need to have the **gh-pages** branch from your fork cloned as a directory named **‘html’**, into your cloned repo:
+
+**'cd honeybot'**
+
+**'git clone -b gh-pages https://github.com/<YOU>/honeybot.git html'**
+
+Your folder structure needs to look as follows:
+
++----------+----------------------------------+
+| honeybot/|          <==== master fork repo  |
++==========+==================================+
+| ├── docs |                                  |
++----------+----------------------------------+
+| |        |└── source                        |
++----------+----------------------------------+
+| ├── html |         <==== gh-pages fork repo |
++----------+----------------------------------+
+| ├── src  |                                  |
++----------+----------------------------------+
+|          |└── honeybot                      |
++----------+----------------------------------+
+
 Generating docs
 ^^^^^^^^^^^^^^^
 
-Once you're set up you can test if sphinx works properly by going to
-`honeybot/docs/`_, opening a terminal and typing **'make html'**.
-This will take the rst files in `honeybot/docs/source*`_
-and 'make' them into html in the *../../honeybot-docs/html* folder.
-If it shows any warning you'll have to fix them before committing, otherwise the documentation
-wont be automatically build once you push your changes to Github.
+Once you’re set up you can test if sphinx works properly in `honeybot/docs/`_ directory, by changing to 'html' folder, opening a terminal and typing **'sphinx-build ../docs/source/ .'**. This will take the *.rst* files in 
+`honeybot/docs/source/`_ and ‘make’ them into html in 'html/' folder that contains the 'gh-pages' branch. If it shows any warning you’ll have to fix them before committing, otherwise the documentation wont be automatically build once you push your changes to Github.
+Next you can 'add' and 'commit' these changes into your fork by typing:
+
+**git add \***
 
-Since I won't provide a full tutorial on how to write rst files here is a useful
+**git commit -m "Commit message"**
+
+Finally, you can make a pull request by typing:
+
+**git push origin gh-pages:gh-pages**
+
+And this'll create a PR in the **gh-pages** branch that'll be analysed by someone in project.
+
+Later do you still need to push the master branch too. Because the *.rst* files are on this branch and were not go to the previus PR:
+
+**git add docs/source \***
+
+**git commit -m "Commit message"**
+
+**git push origin master**
+
+Since I won't provide a full tutorial on how to write *.rst* files here is a useful
 link:
 rst_
 
-
 .. _sphinx: https://www.sphinx-doc.org/en/master/
 .. _here: https://www.sphinx-doc.org/en/master/usage/quickstart.html
 .. _discord: https://discordapp.com/invite/E6zD4XT
@@ -46,4 +87,3 @@ rst_
 .. _honeybot/docs/source/How_Tos/: https://github.com/pyhoneybot/honeybot/tree/master/docs/source/How_Tos
 .. _honeybot/docs/source/Plugins/: https://github.com/pyhoneybot/honeybot/tree/master/docs/source/Plugins
 .. _honeybot/docs/: https://github.com/pyhoneybot/honeybot/tree/master/docs
-.. _honeybot/docs/source*: https://github.com/pyhoneybot/honeybot/tree/master/docs/source