setup.rst: Add docs to setup corobo by codehobbyist06 · Pull Request #665 · coala/corobo

codehobbyist06 · 2021-03-29T21:39:52Z

This illustrates the steps involved in setting up corobo in text mode and with gitter-backend.

Reviewers Checklist

Appropriate logging is done.
Appropriate error responses.
Handle every possible exception.
Make sure there is a docstring in the command functions. Hint: Lookout for
botcmd and re_botcmd decorators.
See that 100% coverage is there.
See to it that mocking is not done where it is not necessary.

This illustrates the steps involved in setting up corobo in text mode and with gitter-backend. Closes coala#668

abhishalya

This is not complete in any way as there are a lot more steps involved. Although, this is a small step in the right direction.

abhishalya · 2021-04-17T17:21:02Z

docs/setup.rst

+     export BOT_PREFIX="any_name"
+     export BACKEND="Text"
+     export BOT_USERNAME="@any_other_name"
+   (**Note:** The BOT_USERNAME always starts with a @ for a person and # for a room)


This is incomplete. And what is BOT_USERNAME?

This was mentioned in the docs. Seems like it is not used now. Will get it removed.
Also, can u pls suggest the points that you mean to get added??

abhishalya · 2021-04-17T17:22:11Z

docs/setup.rst

+#. Clone the err-backend-gitter repository in your "corobo" folder.
+   ::
+     git clone https://github.com/errbotio/err-backend-gitter.git


Nope. We use a submodule pinned to a specific commit, so you should be using that.

Yes.. will get this done.

abhishalya · 2021-04-17T17:23:00Z

docs/setup.rst

+#. Configure the environment variables(for gitter-backend).
+   ::
+     export BACKEND="Gitter"
+     export BOT_EXTRA_BACKEND_DIR="/path_to/err-backend-gitter"


Not required since the path is fixed.

Will get this fixed.

abhishalya · 2021-04-17T17:25:06Z

docs/setup.rst

+     ./oauth.py
+   This will guide you with the gitter token generation process.


On running this file it guides us with the process generating the gitter bit token.

Can you link this file?

This is the file.. https://github.com/errbotio/err-backend-gitter/blob/14a428bdd0597b473605264c822855da979bd916/oauth.py
This point is also mentioned in the gitter backend documentation.

This looks very redundant, and you didn't tell them that this file belongs to the gitter backend directory. I don't think we need this as it is not even a part of corobo.

abhishalya · 2021-04-17T17:27:08Z

docs/setup.rst

+     export ROOMS="rooms_to_join"
+     export BOT_ADMINS="your_gitter_username"
+   (**Note:** The admin user account should be different than the bot account.)
+#. Hurrah!!! the bot is now ready to be deployed. To run the corobo instance use:


deployed seems to be the wrong word here.

Yes, will get this changed.

abhishalya · 2021-04-17T17:27:35Z

docs/setup.rst

+     export GH_TOKEN="your_github_token"
+     export GL_TOKEN="your_gitlab_token"
+     export GH_ORG_NAME="your_github_organisation_name"
+     export GL_ORG_NAME="your_gitlab_organisation_name"
+     export ROOMS="rooms_to_join"
+     export BOT_ADMINS="your_gitter_username"


These exports statements are coming too many times, instead have them bunched up in a single step.

Actually, since I have divided the configuration in steps, the export statements have also been divided accordingly. I will get this done into two parts. One is for simple corobo configuration (with text backend) and other would be with the gitter backend. Dividing in minimum two parts seemed to be essential because it future if we add support for more backends then we can have separate files for each backend. Is this fine??

We don't use text backend, it's merely there for testing reasons. errbot doesn't need special handling for backends, and hence the instructions should be more or less same. For example, we use the same instance for connecting over zulip as well, but we still don't have any special instructions for that.

Ok.. will get this fixed..

Please suggest using .env file, which don't need the export.

Ok. Can I insert link to some external blog regarding working with .env files??

No, not required.

abhishalya · 2021-04-17T17:28:41Z

docs/setup.rst

+   (**Note:** The admin user account should be different than the bot account.)
+#. Hurrah!!! the bot is now ready to be deployed. To run the corobo instance use:
+   ::
+     errbot


Before this is running, the bot account should join all rooms required manually to then listen to those iirc.

Yes, forgot this step.. will get it added..

abhishalya · 2021-04-17T17:29:21Z

docs/setup.rst

+  bot_prefix help
+  bot_prefix history
+
+**Note:** Every time you run a new instance of the bot, it is required to set the environment variables(steps 2 and 7).


Not really required, on a single session the env vars are preserved.

I meant running a new shell instance. Will get this explicitly mentioned..

It would be better to advise them to use .env instead.

abhishalya

Please run this text over a spell or grammar checker. Also take care of max line length, we have this checks over coala repository. Maybe grab a bear from there?

Docs usually take some time, but it's fine as they are supposed to be very easy to understand.

abhishalya · 2021-04-20T15:26:56Z

docs/setup.rst

+Installation
+------------
+
+*  To install corobo, first you need to setup a virtual environment(it is not mandatory but highly recommended). This can be done as follows:


Suggested change

* To install corobo, first you need to setup a virtual environment(it is not mandatory but highly recommended). This can be done as follows:

* To install corobo, first you need to setup a virtual environment. This can be done as follows:

Let's not involve non-venv setups, which most probably won't even work.

abhishalya · 2021-04-20T15:29:51Z

docs/setup.rst

+
+*  To install corobo, first you need to setup a virtual environment(it is not mandatory but highly recommended). This can be done as follows:
+   ::
+     pip3 install virtualenv


Use venv since it ships with python. Let's also add a point of recommending them python 3.6.

abhishalya · 2021-04-20T15:31:47Z

docs/setup.rst

+
+
+Configuring the backend
+------------------------


Suggested change

------------------------

-----------------------

Can you check this, it should be exact the same length as the title above.

abhishalya · 2021-04-20T15:32:45Z

docs/setup.rst

+#. Clone the err-backend-gitter repository in your "corobo" folder.
+   ::
+     git clone https://github.com/errbotio/errbot@a0f35732484c8c0692e123c48653517cffa21a42


Again, this is incorrect. We should be using submodule.

abhishalya · 2021-04-20T15:34:11Z

docs/setup.rst

+     ./oauth.py
+   This will guide you with the gitter token generation process.


This looks very redundant, and you didn't tell them that this file belongs to the gitter backend directory. I don't think we need this as it is not even a part of corobo.

abhishalya · 2021-04-20T15:45:01Z

docs/setup.rst

+     export GH_TOKEN="your_github_token"
+     export GL_TOKEN="your_gitlab_token"
+     export GH_ORG_NAME="your_github_organisation_name"
+     export GL_ORG_NAME="your_gitlab_organisation_name"
+     export ROOMS="rooms_to_join"
+     export BOT_ADMINS="your_gitter_username"


Please suggest using .env file, which don't need the export.

abhishalya · 2021-04-20T15:45:56Z

docs/setup.rst

+     export BOT_ADMINS="your_gitter_username"
+   (**Note:** The admin user account should be different than the bot account.)
+
+#. Hurrah!!! the bot is now ready to rock. To run the corobo instance use:


Suggested change

#. Hurrah!!! the bot is now ready to rock. To run the corobo instance use:

#. Hurrah!!! The bot is now ready to rock. To run the corobo instance use:

abhishalya · 2021-04-20T15:46:29Z

docs/setup.rst

+   (**Note:** You can use the --DEBUG flag to run the bot in debug mode.)
+
+Your corobo instance should now be running. You can chat with the bot by logging in through the admin gitter account and 
+searching its username in the contacts section. You can send it commands via chat.


Suggested change

searching its username in the contacts section. You can send it commands via chat.

searching it's username in the contacts section. You can send it commands via chat.

Also contact section? This could use a better word

abhishalya · 2021-04-20T15:50:21Z

docs/setup.rst

+  bot_prefix history ----> Lists the command history
+
+
+**Note:** To avoid setting the env variables on every new run of shell instance, you can use a .env file to store the vars and run it before running the bot.


Suggested change

**Note:** To avoid setting the env variables on every new run of shell instance, you can use a .env file to store the vars and run it before running the bot.

**Note:** To avoid setting the env variables on every new run of shell instance, you can use a .env file to store the vars and source it before running the bot.

abhishalya · 2021-04-20T15:51:22Z

docs/setup.rst

+
+
+**Note:** To avoid setting the env variables on every new run of shell instance, you can use a .env file to store the vars and run it before running the bot.
+Refer this `link <https://pybit.es/persistent-environment-variables.html>`_ for more info.


No, unless it's an official resource it's better to just avoid it.

Ok. Will get all the changes done and also have the grammar check..

nakuldx · 2021-06-13T04:04:20Z

docs/setup.rst

+Configuring the backend
+-----------------------
+
+- Clone the err-backend-gitter repository in your "corobo" folder.


I don't think quotes are needed here.

Suggested change

- Clone the err-backend-gitter repository in your "corobo" folder.

- Clone the err-backend-gitter repository in your 'corobo' folder.

nakuldx · 2021-06-13T04:05:40Z

docs/setup.rst

+    pip3 install git+https://github.com/errbotio/\
+    err-backend-gitter@14a428bdd0597b473605264c822855da979bd916  


This is not the way we install gitter backend. It is a part of the git submodules so the user just needs to update the git submodule.

nakuldx · 2021-06-13T04:20:13Z

docs/setup.rst

@@ -0,0 +1,95 @@
+Setting Up Corobo


Suggested change

Setting Up Corobo

Setting Up corobo

nakuldx · 2021-06-13T04:24:49Z

docs/setup.rst

+- To install corobo, first you need to install 
+  python (version 3.6 or more) and set up a virtual environment. 
+  This can be done as follows:
+  ::


This is incorrect, you should keep this at the end of the paragraph above. Github somehow renders this but I wasn't able to get this rendered properly locally.

nakuldx · 2021-06-13T04:25:36Z

docs/setup.rst

+    python3 -m venv env
+    cd env
+    source bin/activate ---->  For Linux
+    \Scripts\activate   ---->  For Windows


This could be a bit confusing, let's not specify instructions for windows or other OS.

nakuldx · 2021-06-13T04:31:49Z

docs/setup.rst

+- Hurrah!!! The bot is now ready to rock. To run the corobo instance, use:
+  ::
+    errbot
+  (**Note:** You can use the --DEBUG flag to run the bot in debug mode.)


Add a new line above this.

nakuldx · 2021-06-13T04:32:37Z

docs/setup.rst

+  (**Note:** You can use the --DEBUG flag to run the bot in debug mode.)
+
+Your corobo instance should now be running. You can chat with the bot by
+logging in through the admin Gitter account and searching it's username in


Suggested change

logging in through the admin Gitter account and searching it's username in

logging in through the Gitter admin account and searching its username in

nakuldx · 2021-06-13T04:32:57Z

docs/setup.rst

+Your corobo instance should now be running. You can chat with the bot by
+logging in through the admin Gitter account and searching it's username in
+the conversations tab.
+You can send it commands via chat.


Suggested change

You can send it commands via chat.

You can then send commands via messages.

nakuldx · 2021-06-13T04:33:07Z

docs/setup.rst

+logging in through the admin Gitter account and searching it's username in
+the conversations tab.
+You can send it commands via chat.
+::


Same comment as above.

nakuldx · 2021-06-13T04:33:21Z

docs/setup.rst

+  bot_prefix help    ----> Lists the set of commands available with the bot
+  bot_prefix history ----> Lists the command history


Also not required.

Suggested change

bot_prefix help ----> Lists the set of commands available with the bot

bot_prefix history ----> Lists the command history

bot_prefix help

bot_prefix history

setup.rst: Add docs to setup corobo

fae8cf5

This illustrates the steps involved in setting up corobo in text mode and with gitter-backend. Closes coala#668

codehobbyist06 force-pushed the update_docs branch from bf322a3 to fae8cf5 Compare April 2, 2021 12:31

abhishalya requested changes Apr 17, 2021

View reviewed changes

docs/setup.rst: Make required changes

b78d77d

abhishalya requested changes Apr 20, 2021

View reviewed changes

setup.rst: Update docs

0ad88f4

nakuldx suggested changes Jun 13, 2021

View reviewed changes

		./oauth.py
		This will guide you with the gitter token generation process.

	* To install corobo, first you need to setup a virtual environment(it is not mandatory but highly recommended). This can be done as follows:
	* To install corobo, first you need to setup a virtual environment. This can be done as follows:

	#. Hurrah!!! the bot is now ready to rock. To run the corobo instance use:
	#. Hurrah!!! The bot is now ready to rock. To run the corobo instance use:

	searching its username in the contacts section. You can send it commands via chat.
	searching it's username in the contacts section. You can send it commands via chat.

		bot_prefix history ----> Lists the command history


		Note: To avoid setting the env variables on every new run of shell instance, you can use a .env file to store the vars and run it before running the bot.



		Note: To avoid setting the env variables on every new run of shell instance, you can use a .env file to store the vars and run it before running the bot.
		Refer this `link <https://pybit.es/persistent-environment-variables.html>`_ for more info.

	- Clone the err-backend-gitter repository in your "corobo" folder.
	- Clone the err-backend-gitter repository in your 'corobo' folder.

		pip3 install git+https://github.com/errbotio/\
		err-backend-gitter@14a428bdd0597b473605264c822855da979bd916

	logging in through the admin Gitter account and searching it's username in
	logging in through the Gitter admin account and searching its username in

	You can send it commands via chat.
	You can then send commands via messages.

		bot_prefix help ----> Lists the set of commands available with the bot
		bot_prefix history ----> Lists the command history

Conversation

codehobbyist06 commented Mar 29, 2021

Reviewers Checklist

Uh oh!

abhishalya left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codehobbyist06 Apr 20, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

abhishalya left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codehobbyist06 Apr 20, 2021 •

edited

Loading