From 6d0ad9b21bc73271e4184b146d3289c92992d788 Mon Sep 17 00:00:00 2001 From: Paulo Ferraz Date: Thu, 29 Sep 2022 17:22:25 -0300 Subject: [PATCH 1/2] Documentation - update the contributing guide - Sync *.rst files on master --- docs/source/How_Tos/documentation.rst | 62 ++++++++++++++++++++++----- 1 file changed, 51 insertions(+), 11 deletions(-) diff --git a/docs/source/How_Tos/documentation.rst b/docs/source/How_Tos/documentation.rst index 470483d..2246713 100644 --- a/docs/source/How_Tos/documentation.rst +++ b/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,69 @@ 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//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//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 \*** + +**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 From b3f5b4d4d989787d976311567bf5c4c006da4e22 Mon Sep 17 00:00:00 2001 From: Paulo Ferraz Date: Fri, 30 Sep 2022 15:31:25 -0300 Subject: [PATCH 2/2] Documentaion - Update RST files and README with constraint checks --- README.md | 24 +++++++++++++++++++++++- docs/source/How_Tos/contributing.rst | 23 +++++++++++++++++++++++ docs/source/How_Tos/documentation.rst | 10 +++++----- html | 1 + 4 files changed, 52 insertions(+), 6 deletions(-) create mode 160000 html diff --git a/README.md b/README.md index 98de70c..fa74e67 100644 --- a/README.md +++ b/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 ``` diff --git a/docs/source/How_Tos/contributing.rst b/docs/source/How_Tos/contributing.rst index 3b56526..d64db2e 100644 --- a/docs/source/How_Tos/contributing.rst +++ b/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:: diff --git a/docs/source/How_Tos/documentation.rst b/docs/source/How_Tos/documentation.rst index 2246713..44023ab 100644 --- a/docs/source/How_Tos/documentation.rst +++ b/docs/source/How_Tos/documentation.rst @@ -53,7 +53,8 @@ Your folder structure needs to look as follows: Generating docs ^^^^^^^^^^^^^^^ -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. +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 \*** @@ -66,15 +67,15 @@ Finally, you can make a pull request by typing: 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: +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 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 +Since I won't provide a full tutorial on how to write *.rst* files here is a useful link: rst_ @@ -86,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 \ No newline at end of file diff --git a/html b/html new file mode 160000 index 0000000..e340990 --- /dev/null +++ b/html @@ -0,0 +1 @@ +Subproject commit e340990205fda43312173090652fc6be0cc7b7fe