Better docs
LunarWatcher opened this issue · 18 comments
The documentation is a mess and a lot of it is non-existent. Documentation needs to be added as soon as possible
Current progress
- Setup documentation - thanks to Whispres
- Command/listener documentation
- Extending existing ones
- Code documentation (Javadoc/Kdoc) - not very critical.
- Interaction guide
- rank documentation
Notes
- Interaction guide
A basic "how to use the bot". Creating command and listener documentation would take care of a large part of this, but stuff like understanding arguments (currently a comma-separated list, #61 changes that a bit but still) for commands, also the CLI-style arguments (--somename "argument content").
Should also cover ranks
I am interested in helping generate docs. I see under CONTRIBUTING.md the docs should be organized in the Wiki. Do you have any other organizational system in mind for documentation? Which types of docs would you like to prioritize? I am currently studying REST API Documentation and would appreciate the practice, but I am more than happy to work on any assignment to gain more experience.
The top priority atm is creating proper setup docs. Then there's a huge need for expansion docs (specifically on adding custom commands and listeners, and adding new sites). The Database class, along with the CommandCenter class, needs extra attention since these are highly used when extending the bot with i.e. new commands. Same applies to the AbstractCommand class and AbstractListener (
There's a general need for Javadoc/KDoc in the code as well, but if it's covered in the wiki it's not as critical.
As for an organization system, it just goes in the wiki in separate pages for separate topics.
Gotcha. I'll focus on the proper setup docs first. I need to ask a few basic questions to get started:
Environment
- Aside from the dependencies, what software, if any, should be downloaded and installed in order to write, compile and run the chatbot code?
- What tests can be run to ensure the software has been properly installed before the developer gets started?
- Is there a list of known errors and solutions for setting up the environment?
- Are there any instructions specific to a particular OS platform a developer might be working with? (i.e., Is the code compatible as-is with Windows, Mac OS X, Linux, etc.?)
Configuration
- Once the code has been downloaded from the repository, do any of the directories need to be modified aside from
Config.py_example? - The chatbot appears to be configured to work with Discord, Twitch, Stack Exchange and Stack Overflow. How does a developer connect their chatbot to their accounts? Does the chatbot require its own separate account?
I'm still familiarizing myself with the project and will have plenty more questions later.
- IntelliJ and/or PyCharm, Java 8 and Python 3.6+. IntelliJ is recommended since it does support Python editing as well as Java, all though I assume PyCharm can do the same it's mostly because of Gradle. If the Java port isn't used, PyCharm. If the Python module isn't used, IntelliJ. Java 8 is only necessary if the Java port is used, and Python 3.6+ is only necessary if the NN module/Python bot is used. For the revision command to work, Git must be installed and added to the PATH environment variable or somehow else be available from a regular command prompt.
- There isn't really any installation. However, creds.properties-example needs to be renamed to creds.properties, and the necessary credentials need to be added. Bot.properties can be configured with stuff like home rooms for the bot and hardcoded admins. There isn't really any other validation than it successfully connecting to the enabled chat sites.
- Not at the moment (readme.md covers some of it though, but it's outdated and lacking)
- It should be universally compatible out of the box (I have only tested on Windows though, so I haven't validated it. But since it's Java and Python without any OS specific stuff, it should be fine.
- As mentioned earlier, bot.properties and creds.properties-example.
- The SE network (meta.stackexchange, stackexchange and stackoverflow) requires a separate account. Discord requires registration of a bot application here (plain URL:
https://discordapp.com/developers/applications/me), and Twitch requires app registration here (plain URL:https://glass.twitch.tv/console/apps/create) in addition to a separate account. It can of course be run of someones account (without sock accounts, the exception applies to Discord where an app has to be registered).
Some extra info I think might me useful given the last question: sites are togglable. Not filling in the credentials results in the site not being launched. I'm gonna add some more comments in creds.properties(-example) as a part of the next commit to make what credentials is required more obvious (since some of the sites use some of the fields but not others due to API differences)
Sorry for the absence. I had a few personal and professional obligations as well as a fatal technical malfunction pop up on me. The technical malfunction resulted in cross-device data loss, so I will need to rewrite the unpublished wiki documents I was working up for the NN-Chatbot. Thank you for your patience.
I do have a quick question about the dependencies. I see a list of dependencies in the Readme, and a file called requirements.txt has a similar list. Are the programs in the requirements.txt file also dependencies?
Sorry about the late reply, I missed your reply.
requirements.txt is the Python dependencies. It's in a format that enables installing using pip (the Python package manager). All of them should be listed in README.md, but the exact specs are in requirements.txt
I see you have someone who may be helping with the API docs. Do you still need anyone to help in this area?
Yeah, there's still some stuff missing. I've been planning to get around to it myself, and I'll probably get some of it done this weekend (or earlier), but there's a lot to cover.
If you want to help, there's a list in the original post covering stuff that needs to be done.
Great. I'm new to API docs, so I'll try to set it up so I can play with it and then wrap my head around what you already have documented. Then I can find what's missing to add to it. I already installed Python on my system.
I've spent most of the day trying to install it on my Windows machine. No success yet. Dependencies and path issues. Also, one of the required packages (tensorflow) may not work with the newest version of Python according to its docs. I see the need for clear documentation.
In fact, for the life of me I cannot install tensorflow. Pip says there is no such file. I installed Scipy already. I installed other dependencies as well.
Also, where does the raw_data folder go?
I'll take a look at it later today.
The raw_data folder goes whereever you run the command from. If you're in C:/path/to/project/root/ and run python Network/bot.py, you'd put it in the root directory.
But if you can't install dependencies, and critically Tensorflow, you can't run the Python module of the project. Like I said, I'll look into it later. I remember some version of a dependency requiring manual installation from a wheel file, but I can't remember if this applies here.
What version of Python and Windows are you using?
I have everything installed now with the latest packages except I still cannot install Tensorflow.
Python=3.7.0
Windows 10
Could not find a version that satisfies the requirement tensorflow (from versions: )
No matching distribution found for tensorflow
Ok. I found that Tensorflow does not support Python 3.7. I installed 3.6.6 and was able to install Tensorflow. Yay!
I am confused where the Readme file says "Rename Config.py_example to Config.py and fill in the necessary values." I'm not sure which values I need to change in the Config.py file.
Here is my current error:
Traceback (most recent call last):
File "C:\Users\chris\NN-chatbot\Network\bot.py", line 6, in
import Config
File "C:\Users\chris\NN-chatbot\Network\Config.py", line 19, in
email = str(config[CONFIG_KEY]["akredshaw@gmail.com"])
File "C:\Users\chris\AppData\Local\Programs\Python\Python36\lib\configparser.py", line 959, in getitem
raise KeyError(key)
KeyError: 'creds'
I'm gonna do some refactoring and remove the Python bot. It would get rid of the config file there, so it should be slightly easier to set up. It's not maintained anyways.
(Clarification: The Python bot is a Python backend for the neural net for Discord and SE. The Java one is the only one being actively developed after I started having threading issues with it. The API does, like I mentioned in #64, need cleanup).
Tensorflow is version sensitive, so it not supporting 3.7 yet would make sense, since 4.7 is quite new. Either way, glad you figured it out :)
Edit: The changes have been pushed. Removed a bunch of redundant code in the system. The config files weren't actually necessary xd
Please forgive my lack of knowledge. Here's where I am now:
- I am still unable to get it running. The Readme says "Rename Config.py_example to Config.py and fill in the necessary values." Which values do I change in Config.py?
When I run: python bot.py I get
Traceback (most recent call last):
File "bot.py", line 6, in
import Config
File "C:\Users\chris\NN-chatbot\Network\Config.py", line 19, in
email = str(config[CONFIG_KEY]["akredshaw@gmail.com"])
File "C:\Users\chris\AppData\Local\Programs\Python\Python36\lib\configparser.py", line 959, in getitem
raise KeyError(key)
KeyError: 'creds'
- Don't I need to run bot.py before I can compile and run BotCore.java?
- I assume the API will be for connecting to Discord, Stack Exchange, Twitch, etc, so I will be referencing their API docs to connect. Am I on the right track?
I'm sorry, that's on me.
-
You don't need the config.py any more. Updated the docs, but missed the readme xd
-
You don't need that. bot.py and BotCore.java can run independently of each other. Tbh, if you don't have a decent GPU, I don't recommend running the ML parts unless your computer can handle it.
-
The bot itself connects to those three, yes. For SE there's a custom API, but Discord uses Discord4J and for twitch there's Twitch4J. You can run on a single site, some, or all.
To run the Java bot, the ones you need to change are bot.properties and creds.properties. They both have a bunch of comments in them, so it should be clear what it does. Missing username/password or other necessary config on any given site will also disable the site, so you don't have to run it on all the sites for the bot to work.
I'll update the readme, but if you pull the newest version, all dependency on config.py has been removed, and the Python bot is gone too. (The neural net, the part that is in bot.py is still around though. It is after all half the bot).
Do you have the endpoint URL's for API documentation?
There aren't any, aside those that connect the sites. There's only one there's written a custom wrapper around though. The other two use other API's (as I mentioned earlier).
So I'm not sure if endpoint URL's can be applied here