Caddy: Documentation Feedback (v2)

[sethgrid]

There is a dramatic lack of examples that can be learned from. I'm trying to set up logging. From the docs, I can't tell exactly what to do. It looks like a top level key for logging and then nested stuff. And I have to read through every option and grok what is going on. It would be great to have "near ready-to-go" examples, not snippets, but full examples. As far as I can tell, I have to hand craft crazy nested json to do anything.

Sample cases:
simple file server with log rotation

simple reverse proxy to forward requests to your go application running on port $port with log rotation

etc.

[francislavoie]

Yeah, the official documentation is currently a work-in-progress. @mholt gave a talk recently about the challenges involved. Near the end of the video he shows off a preview of how the v2 documentation will eventually look. The docs in the wiki are temporary, just meant to be enough to get started for those willing to put the effort in trying it out during the beta period.

For now, I think the best course of action is asking in https://caddy.community for help in crafting your config. Lots of smart cookies frequent the forums, I'm sure you'll be able to get the help you need :smile:

[mholt]

Hi, yes, @francislavoie is right -- my top priority right now is better docs. I've spent all day on them and will be spending most of the holidays on them as well.

I hope you'll find that talk interesting -- the last 15 minutes or so give a high-level idea of what we're accomplishing with the new documentation system. You can see a little screenshot as a teaser here, if you don't want to watch the whole video: https://twitter.com/mholt6/status/1199066138753155072

There is a lot of complexity in Caddy 2 that we're making very accessible in this new system. Caddy 2 is extremely powerful, flexible, and extensible, so the reference portion of the docs will be pretty thick, but it will also have great features to assist your comprehension such as interactive JSON navigation, rich tooltips and breadcrumbs, etc. All the docs are generated automatically from the code. So, that's pretty complex and will take a little time. Stay tuned for updates here in the next few weeks.

Once I get this working, I'll be focusing on the less automatic part of the new docs, which include explanatory guides, tutorials, examples/samples, and more on the Caddyfile.

Don't be surprised though if the Caddyfile and its docs are the last things to be finished before we roll out of beta: in Caddy 2, the Caddyfile is just layered on top (but is a first-class citizen, don't get me wrong), so we absolutely have to make sure the core of Caddy right before the Caddyfile can be polished.

Oh, and the new docs have a dark theme.

[mholt]

A better preview of the new JSON docs: https://twitter.com/caddyserver/status/1209205500165836800

[mholt]

New docs are up: https://caddyserver.com/docs/

Will continue working on them of course, but the Caddyfile docs will be the last thing to be added, since it's still rapidly changing.