Documentation - Githubissues

fosslinux commented 5 years ago

I think the current thing that's stopping people from using BitBot is the lack of documentation. There is currently very very little documentation and most of it is relying on the user to guess for most things.

I think documentation should be a top priority, at this stage of development.

jesopo commented 5 years ago

I'd like some advice on how best to tackle this - where to start, how to present that documentation, etc. <3

Jan69 commented 5 years ago

I'd think it best to have brief syntax on the bot itself, but a nice, detailed one with examples on a website or wiki or such... and ideally the same docs would be part of the repo, just hosted/converted/mirrored/etc on somewhere (probably easiest to use markdown (readable in raw file form) and convert to html for pretty presentation, could be done with github pages, even, just make a separate branch (or folder) for docs, and it can convert pages for you, using jekyll (though would need to make/find a theme that'd work))

Github "wiki" is a good place to put common FAQ questions, (which might also be in proper docs), flaws being that 1) can't be exported out of github, afaik 2) no styling, you have one giant sidebar menu with ALL the pages, and can only use markdown like in these comments, (could use an external wiki or something...but that's probably not worth it...)

could start with most used, and useful modules and commands, (also ideally would mention stuff like bef=befriend duck, but shortened, that can be later added tho), which sed flags are allowed, which config options affect it, how to use it (maybe with a link to a proper tutorial even), etc, same for others

presentation-wise I'd think a collapsed list of modules, which list the pages related to that module when expanded, such as command help pages.

I will definitely be up to spell-check stuff and such ;P

Mikaela commented 5 years ago

In case of separate branch for docs, git checkout --orphan gh-pages might be helpful. I am not sure if the branch has to be named gh-pages anymore.

can't be exported out of github, afaik

git clone https://github.com/jesopo/bitbot.wiki.git

Mikaela commented 5 years ago

How do I turn on titlefetching? Which module/plugin does that?

How do I give someone chanop permissions in a specific channel?

jesopo commented 5 years ago

!config c auto-title on which requires +o, !access add <nickname> config (per-channel) or !givepermission <nickname> config (per-server)

Mikaela commented 5 years ago

2019-08-16T12:36:09+0300 <+Mikaela> !access add Cradamy config
2019-08-16T12:36:10+0300 bittibotti (Notice) [ChanAccess] You do not have permission to do this

And how do I config without being on a channel? Why don't I have the permission?

For future reference that is not necessary here: what was the command to change between NOTICE/PRIVMSG again?

jesopo commented 5 years ago

you need +o to be able to change channel access flags.

!config c command-method notice vs !config c command-method privmsg

Mikaela commented 5 years ago

What I learned from jesopo on IRC while being confused just now:

ops are recognised as ops when they are +o automagically without any need to change anything
in order to have channel op always have op permissions, they have to op themselves via ChanServ and then !access add opnick * by themselves
bitbot philosophy is that the owner is not supposed to have control over channel specific matters (as opposed to Supybot where owner is root).

Also my idea is that once the questions here are in documentation, you can three dots -> hide ~~comment ->~~ and in the prompt select resolved from the dropdown box.

jesopo commented 5 years ago

🤔

Mikaela commented 5 years ago

How does weather work?

2019-08-19T12:05:19+0300 <@Mikaela> !weather
2019-08-19T12:05:24+0300 bittibotti (Notice) [Weather] Please set location, e.g.: !config u location London, GB
2019-08-19T12:05:30+0300 <@Mikaela> !config u location Lauttasaari
2019-08-19T12:05:34+0300 <@Mikaela> !weather
2019-08-19T12:05:35+0300 bittibotti (Notice) [Weather] Please set location, e.g.: !config u location London, GB
2019-08-19T12:05:59+0300 <@Mikaela> !config u location Lauttasaari
2019-08-19T12:06:08+0300 <@Mikaela> !config u location Lauttasaari, FI
2019-08-19T12:06:10+0300 <@Mikaela> !ping
2019-08-19T12:06:11+0300 bittibotti (Notice) [Pong] Pong!
2019-08-19T12:06:17+0300 <@Mikaela> !weather Lauttasaari
2019-08-19T12:06:24+0300 <@Mikaela> !ping
2019-08-19T12:06:24+0300 bittibotti (Notice) [Pong] Pong!

I have set the API key in bot.conf. Another request would be giving feedback on invalid commands at least on specific channels like my spam one and potentially include hints on what I am doing wrong.

EDIT:

Sep 02 16:37:59 relpda python3[14799]: 2019-09-02T16:37:59.726 [ERROR] failed to call event "received.message.channel"
Sep 02 16:37:59 relpda python3[14799]: Traceback (most recent call last):
Sep 02 16:37:59 relpda python3[14799]:   File "/home/bitbot/bitbot/src/EventManager.py", line 192, in _call
Sep 02 16:37:59 relpda python3[14799]:     returned = hook.call(event)
Sep 02 16:37:59 relpda python3[14799]:   File "/home/bitbot/bitbot/src/EventManager.py", line 51, in call
Sep 02 16:37:59 relpda python3[14799]:     return self.function(event)
Sep 02 16:37:59 relpda python3[14799]:   File "/home/bitbot/bitbot/modules/commands/__init__.py", line 308, in channel_message
Sep 02 16:37:59 relpda python3[14799]:     command_prefix=command_prefix)
Sep 02 16:37:59 relpda python3[14799]:   File "/home/bitbot/bitbot/modules/commands/__init__.py", line 246, in command
Sep 02 16:37:59 relpda python3[14799]:     hook.call(new_event)
Sep 02 16:37:59 relpda python3[14799]:   File "/home/bitbot/bitbot/src/EventManager.py", line 51, in call
Sep 02 16:37:59 relpda python3[14799]:     return self.function(event)
Sep 02 16:37:59 relpda python3[14799]:   File "/home/bitbot/bitbot/modules/config.py", line 180, in config
Sep 02 16:37:59 relpda python3[14799]:     result = self._config(export_settings, target, setting, value)
Sep 02 16:37:59 relpda python3[14799]:   File "/home/bitbot/bitbot/modules/config.py", line 98, in _config
Sep 02 16:37:59 relpda python3[14799]:     validated_value = export_settings[setting].parse(value)
Sep 02 16:37:59 relpda python3[14799]:   File "/home/bitbot/bitbot/modules/location.py", line 11, in parse
Sep 02 16:37:59 relpda python3[14799]:     return self._func(value)
Sep 02 16:37:59 relpda python3[14799]:   File "/home/bitbot/bitbot/modules/location.py", line 23, in _get_location
Sep 02 16:37:59 relpda python3[14799]:     "q": s, "key": self.bot.config["opencagedata-api-key"], "limit": "1"
Sep 02 16:37:59 relpda python3[14799]:   File "/home/bitbot/bitbot/src/Config.py", line 17, in __getitem__
Sep 02 16:37:59 relpda python3[14799]:     return self._config[key]
Sep 02 16:37:59 relpda python3[14799]: KeyError: 'opencagedata-api-key'

Mikaela commented 5 years ago

!config bot configurable-nameservers off - preventing channel specific DNS servers from getting used, due to having encrypted DNS through dnscrypt-proxy/unbound/stubby/similar and not wanting to allow security to be downgraded through bitbot performing plaintext DNS queries.

Mikaela commented 5 years ago

On my weather thing, you need two API keys:

https://openweathermap.org/api - weather data
https://opencagedata.com/users/sign_up - location

Mikaela commented 5 years ago

Would there be any idea in a "bitbot rosetta" (like Pacman Rosetta? E.g.

Bitbot: !modules | Limnoria: !list Bitbot: !commands \<module> | Limnoria: !list \<plugin>

I don't know how many other differences there are, but this example is very basic and another useful could be configuration, I have no idea how it works with Bitbot, but Limnoria has @config list for the root config variables and the response has @ for "directories" and # for options that are also channel specific (and some "directories" may also be variables themselves).

jamestomasino commented 5 years ago

I think you've got a few big categories to consider for documentation:

Installer/maintainer documentation, which would be great on the system side as man page, of possible. It could be concerned with install, updates, security, etc.
Core use by operators in IRC. How do you set configuration and access? The location of this help is a little less clear. Having it in the bot itself may be presumptuous if the admin doesn't try know how to even use it. Web based is a safe default but maybe mirroring it in multiple places is better.
User help. This is what I'd expect a user to interact with when they /msg bitbot help. This is probably the hardest component to do thoroughly. I'd suggest referencing bitlebee for a modular system and how it handles help. I think BitBot is already on a similar path.

poVoq commented 1 year ago

This is sadly still extremely lacking and I have to pry all the details out of the module source-code :(

I started documenting some of the features I find most important here:

https://wiki.f-hub.org/books/irc-network/page/channel-bot

But it still needs a lot of work.

bitbot-irc / bitbot

Documentation #98