Major refactoring and full documentation

Arkoniak · Jun 21, 2020 · 69daf12 · 69daf12 · Arkoniak · Jun 21, 2020
1 parent cdf0089
commit 69daf12
Show file tree

Hide file tree

Showing 18 changed files with 2,172 additions and 95 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -12,9 +12,8 @@ jobs:
     strategy:
       matrix:
         version:
-          - '1.0'
           - '1.3'
-          - '1.5'
+          - 'nightly'
         os:
           - ubuntu-latest
           - macOS-latest
@@ -43,6 +42,7 @@ jobs:
       - run: julia --project=docs -e '
           using Pkg;
           Pkg.develop(PackageSpec(; path=pwd()));
+          Pkg.add(PackageSpec(url="https://github.com/Arkoniak/Documenter.jl", rev="repo_url"));
           Pkg.instantiate();'
       - run: julia --project=docs docs/make.jl
         env:

diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "Telegram"
 uuid = "1da6f4ae-116c-4c38-8ee9-19974ff3601d"
 authors = ["Andrey Oskin"]
-version = "0.1.0"
+version = "0.2.0"
 
 [deps]
 HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"

diff --git a/README.md b/README.md
@@ -5,44 +5,104 @@
 [![Build Status](https://travis-ci.com/Arkoniak/Telegram.jl.svg?branch=master)](https://travis-ci.com/Arkoniak/Telegram.jl)
 [![Coverage](https://codecov.io/gh/Arkoniak/Telegram.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/Arkoniak/Telegram.jl)
 
-Telegram api wrapper
+Simple [Telegram Messaging](https://telegram.org/) SDK with logging and bot facilities. Package was built with first-class support of telegram as instant message backend for various notification and reporing systems. So, simpliest way to use this package is by doing something like this
+
+```julia
+using Telegram, Telegram.API
+tg = TelegramClient("YOUR TOKEN", chat_id = "YOUR CHAT_ID")
+
+# Some lengthy calculation
+# ...
+
+sendMessage(text  = "Calculation complete, result is $result")
+```
+
+Please refer to [documentation](https://Arkoniak.github.io/Telegram.jl/dev) to learn how to properly setup telegram credentials and use package in general. 
 
 # Installation
 
-Currently package is not registered, so it should be installed from source
+Package is registered so you can install it in a usual way
 
 ```julia
 julia> using Pkg
-julia> Pkg.add("https://github.com/Arkoniak/Telegram.jl.git")
+julia> Pkg.add("Telegram")
 ```
 
 # Usage
 
+## Telegram API
+
 Usage is straightforward, [Telegram API methods](https://core.telegram.org/bots/api#available-methods) are in one to one correspondence with this Julia wrapper. You need to create connection and then simply call necessary methods
 
 ```julia
+julia> using Telegram, Telegram.API
 julia> token = "HERE SHOULD BE YOUR TOKEN"
-julia> client = TelegramClient(token)
+julia> TelegramClient(token)
 
-julia> getMe(client)
-JSON3.Object{Base.CodeUnits{UInt8,String},Array{UInt64,1}} with 2 entries:
-  :ok     => true
-  :result => {…
+julia> getMe()
+JSON3.Object{Array{UInt8,1},SubArray{UInt64,1,Array{UInt64,1},Tuple{UnitRange{Int64}},true}} with 7 entries:
+  :id                          => 123456789
+  :is_bot                      => true
+  :first_name                  => "Awesome Bot"
+  :username                    => "AwesomeBot"
+  :can_join_groups             => true
+  :can_read_all_group_messages => false
+  :supports_inline_queries     => false
 ```
 
-You can necessary arguments in methods, but some subset can be set in `client` itself
+Mainly you need to set arguments, but `chat_id` can be set directly in `TelegramClient` 
 
 ```julia
 julia> token = "HERE SHOULD BE YOUR TOKEN"
-julia> client = TelegramClient(token; chat_id = "HERE SHOULD BE CHAT_ID")
+julia> TelegramClient(token; chat_id = "HERE SHOULD BE CHAT_ID")
 
-julia> sendMessage(client, text = "Hello, world!")
+julia> sendMessage(text = "Hello, world!")
 ```
-or equivalently
+
+You can send files and other `io` objects
 
 ```julia
-julia> token = "HERE SHOULD BE YOUR TOKEN"
-julia> client = TelegramClient(token)
+julia> sendPhoto(photo = open("picture.jpg", "r"))
+julia> io = IOBuffer()
+julia> print(io, "Hello world!")
+julia> sendDocument(document = "hello.txt" => io)
+```
+
+## Logging
+
+You can use [Telegram.jl](https://github.com/Arkoniak/Telegram.jl) together with [LoggingExtras.jl](https://github.com/oxinabox/LoggingExtras.jl) to create powerful logging with insta messaging in case of critical situations
+
+```julia
+using Telegram
+using Logging, LoggingExtras
+
+# considering that token and chat_id variables are set as corresponding 
+# environment variables
+tg = TelegramClient(ENV["TG_TOKEN"], chat_id = ENV["TG_CHAT_ID"])
+tg_logger = TelegramLogger(tg; async = false)
+demux_logger = TeeLogger(
+    MinLevelLogger(tg_logger, Logging.Error),
+    ConsoleLogger()
+)
+global_logger(demux_logger)
+
+@warn "It is bad"        # goes to console
+@info "normal stuff"     # goes to console
+@error "THE WORSE THING" # goes to console and telegram
+@debug "it is chill"     # goes to console
+```
+
+## Bots
+
+You can create bot very easy with the `run_bot` command. Here is for example Echo bot
+```julia
+using Telegram, Telegram.API
+
+token = ENV["TG_TOKEN"]
+tg = TelegramClient(token)
 
-julia> sendMessage(client; text = "Hello, world!", chat_id = "HERE SHOULD BE CHAT_ID")
+# Echo bot
+run_bot() do msg
+    sendMessage(text = msg.message.text, chat_id = msg.message.chat.id)
+end
 ```
diff --git a/docs/make.jl b/docs/make.jl
@@ -9,10 +9,14 @@ makedocs(;
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
         canonical="https://Arkoniak.github.io/Telegram.jl",
+        siteurl="https://github.com/Arkoniak/Telegram.jl",
         assets=String[],
     ),
     pages=[
         "Home" => "index.md",
+        "API Reference" => "reference.md",
+        "Usage" => "usage.md",
+        "Developer guide" => "developers.md"
     ],
 )
 

diff --git a/docs/src/developers.md b/docs/src/developers.md
@@ -0,0 +1,20 @@
+# Developer guide
+
+Please note, that api functions themselves are not written manually, but automatically generated by parsing [https://core.telegram.org/bots/api](https://core.telegram.org/bots/api) site. So, if you find any inconsistences, missing docstrings or missing methods please do not make changes to `src/telegram_api.jl` or `reference.md`. Instead you should change scraping script accordingly. This script can be found in `extras` directory and in order to build new docs and methods you should do the following
+
+```sh
+sh> cd extras
+sh> julia
+julia> ]
+pkg> activate .
+(extras)> instantiate
+```
+
+After that you can exit julia session and run
+```sh
+sh> julia make.jl
+```
+command. It will create two files:
+* `src/telegram_api.jl` which contains all methods names and corresponding docstrings
+* `docs/src/reference.md` which contains complete [API Reference](@ref) page.
+
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -3,56 +3,30 @@ CurrentModule = Telegram
 ```
 
 # Telegram
+Simple [Telegram Messaging](https://telegram.org/) SDK with logging and bot facilities. Package was built with first-class support of telegram as instant message backend for various notification and reporing systems. So, simpliest way to use this package is by doing something like this
 
-Supported methods
-- [X] getMe
-- [X] sendMessage
-- [ ] forwardMessage
-- [ ] sendPhoto
-- [ ] sendAudio
-- [ ] sendDocument
-- [ ] sendVideo
-- [ ] sendAnimation
-- [ ] sendVoice
-- [ ] sendVideoNote
-- [ ] sendMediaGroup
-- [ ] sendLocation
-- [ ] editMessageLiveLocation
-- [ ] stopMessageLiveLocation
-- [ ] sendVenue
-- [ ] sendContact
-- [ ] sendPoll
-- [ ] sendDice
-- [ ] sendChatAction
-- [ ] getUserProfilePhotos
-- [ ] getFile
-- [X] kickChatMember
-- [X] unbanChatMember
-- [X] restrictChatMember
-- [X] promoteChatMember
-- [X] setChatAdministratorCustomTitle
-- [X] setChatPermissions
-- [X] exportChatInviteLink
-- [ ] setChatPhoto
-- [X] deleteChatPhoto
-- [X] setChatTitle
-- [X] setChatDescription
-- [X] pinChatMessage
-- [X] unpinChatMessage
-- [X] leaveChat
-- [X] getChat
-- [X] getChatAdministrators
-- [X] getChatMembersCount
-- [X] getChatMember
-- [X] setChatStickerSet
-- [X] deleteChatStickerSet
-- [ ] answerCallbackQuery
-- [ ] setMyCommands
-- [ ] getMyCommands
-
-```@index
+```julia
+using Telegram, Telegram.API
+tg = TelegramClient("YOUR TOKEN", chat_id = "YOUR CHAT_ID")
+
+# Some lengthy calculation
+# ...
+
+sendMessage(text  = "Calculation complete, result is $result")
 ```
 
+## Installation
+Package is registered so you can install it in a usual way
+
+```julia
+julia> using Pkg
+julia> Pkg.add("Telegram")
+```
+
+## General methods
+
+In addition to [API Reference](@ref) methods, there is a number of methods which add some julian functionality like bots and logging facilities.
+
 ```@autodocs
 Modules = [Telegram]
 ```