Start some real documentation (#15)

Add a small intro/installation section; document progress logging and the exported API.

Co-authored-by: Takafumi Arakaki <[email protected]>

Author: c42f

README.md

@@ -5,5 +5,9 @@
 [![Build Status](https://github.com/c42f/TerminalLoggers.jl/workflows/CI/badge.svg)](https://github.com/c42f/TerminalLoggers.jl/actions?query=workflow%3ACI)
 [![Codecov](https://codecov.io/gh/c42f/TerminalLoggers.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/c42f/TerminalLoggers.jl)
 
-`TerminalLoggers` contains user interface utilities for displaying log messages
-in text terminals.
+TerminalLoggers provides a logger type `TerminalLogger` which can format your
+log messages in a richer way than the default `ConsoleLogger` which comes with
+the julia standard `Logging` library.
+
+Read the [documentation](https://c42f.github.io/TerminalLoggers.jl/stable) for
+more information.

docs/src/index.md

@@ -1,8 +1,60 @@
 # TerminalLoggers.jl
 
-```@index
+TerminalLoggers provides a logger type [`TerminalLogger`](@ref) which can
+format your log messages in a richer way than the default `ConsoleLogger` which
+comes with the julia standard `Logging` library.
+
+
+## Installation and setup
+
+```julia-repl
+pkg> add https://github.com/c42f/TerminalLoggers.jl
+```
+
+To use `TerminalLogger` in all your REPL sessions by default, you may add a
+snippet such as the following to your startup file (in `.julia/config/startup.jl`)
+
+```julia
+atreplinit() do repl
+    try
+        @eval begin
+            using Logging: global_logger
+            using TerminalLoggers: TerminalLogger
+            global_logger(TerminalLogger())
+        end
+    catch
+    end
+end
+```
+
+
+## Progress bars
+
+`TerminalLogger` displays progress logging as a set of progress bars which are
+cleanly separated from the rest of the program output at the bottom of the
+terminal. Try an example like the following
+
+```julia
+global_logger(TerminalLogger(right_justify=120))
+for i=1:100
+    if i == 50
+        @warn "Middle of computation" i
+    end
+    sleep(0.01)
+    @info "Some progress" progress=i/100
+end
+@info "Done"
 ```
 
-```@autodocs
-Modules = [TerminalLoggers]
+!!! note
+    Rendering progress bars separately doesn't yet work on windows due to
+    limitations of the windows console and its interaction with libuv.
+    We expect this will eventually be solved with some combination of libuv
+    updates and the new windows terminal.
+
+
+## API Reference
+
+```@docs
+TerminalLogger
 ```

src/TerminalLogger.jl

@@ -2,8 +2,9 @@
     TerminalLogger(stream=stderr, min_level=$ProgressLevel; meta_formatter=default_metafmt,
                    show_limited=true, right_justify=0)
 
-Logger with formatting optimized for readability in a text console, for example
-interactive work with the Julia REPL.
+Logger with formatting optimized for interactive readability in a text console
+(for example, the Julia REPL). This is an enhanced version of the terminal
+logger `Logging.ConsoleLogger` which comes installed with Julia by default.
 
 Log levels less than `min_level` are filtered out.