JuliaLogging: Everything you need for logging in Julia

[fredrikekre]

The JuliaLogging organization

Back in June we created the JuliaLogging organization with the intention to collect and promote various logging packages in Julia. It is my understanding that logging in Julia is quite underutilized, probably because the Logging standard library is quite limited, and the knowledge of extension packages are not so widespread.

Since we created the organization I have been procrastinating every now and then writing documentation for the organization. The result of this is now published: https://julialogging.github.io/. The intention of this document is to both give an overview of the many packages that extend the Logging standard library, and also to document and demonstrate common logging operations (routing, filtering, transforming, file rotation, formatting, etc). Please have a look!

Contribute!

If you find something confusing, missing or something that can be improved I encourage you to contribute. Probably there are logging related packages that I have missed that should be included (note that you don’t have to move the package to the JuliaLogging organization in order to document it there).

I tried to make it easy and fun to contribute: If you clone the repository and run make from the root LiveServer.jl will start a web server on http://localhost:8080 that will automatically monitor changes to the source files, re-build the HTML pages, and automatically refresh the webpage in the browser. I have found this workflow to be very nice when writing documentation since you get to see the result directly.

Miscellaneous comments

• The structure of https://julialogging.github.io/ is based on the Diátaxis Framework. This is the first time I try to structure docs like that. Does anyone have any thoughts on this? Personally I found it difficult to separate what they refer to as “how-to” and “tutorial”.
• Various new features in Documenter.jl were prompted by, and show-cased at, https://julialogging.github.io/. In particular:
  • Colored output from @example and @repl blocks (Documenter.jl#1441, Documenter.jl#1628),
  • Correct line numbers for @example and @repl output (Documenter.jl#1634),
  • Prerendering for code highlighting (Documenter.jl#1627) so you can use your favorite highlighter,
  • Support for deploying without versions (Documenter.jl#1616) such that https://julialogging.github.io/ is just https://julialogging.github.io/ and not https://julialogging.github.io/stable/.

Happy logging!

[goerz]

@fredrikekre

The structure of https://julialogging.github.io/ is based on the Diátaxis Framework . This is the first time I try to structure docs like that. Does anyone have any thoughts on this?

I’m a huge fan of that style of documentation and try to use it in all of my projects

Personally I found it difficult to separate what they refer to as “how-to” and “tutorial”.

Looking at https://julialogging.github.io, I think you got it pretty much right.

Tutorials are supposed to be didactic lessons designed to introduce new users to some aspect of the package. They generally need to be somewhat “from scratch” and should be reproducible from top to bottom. I typically write these as Jupyter notebooks (or Literate.jl or something like that for Julia)

Howtos assume a user that’s already somewhat familiar with the package; they know what they want to do, and just need to be told how to achieve their goal. These can be much more concise, typically just a couple of paragraphs for each “Howto”. They don’t need to be complete, just showing relevant code-snippets should be enough (although I sometimes have hidden “tearup”/“teardown” code in my docs to enable CI checking). If there are multiple ways to do something, the Howto can list all of them (which would often be confusing in a tutorial, where it’s more didactic to focus on just the most common path)

[cormullion]

This is really good, definitely an example to try and emulate, and it sets a high bar!

My one suggestion would be to have an introduction section, showing a simple example and show some possibilities. Then move the package overview to an Explanations section further down, since it probably belongs after a tutorial.

[Alec_Loudenback]

Love the logo!