[dancer-users] Snigdha Dagar's (our OPW participant) work has been merged!

[Sawyer X]

Hi everyone,

I had a few conferences, lots of work, and then, of course, I was under the
weather, so not much was heard from me in a while. Consider yourselves
lucky. :)

However, having regained enough composure to finally merge the massive PR
Snigdha Dagar has submitted as part of her work on overhauling the
documentation, I'd like to share it with you, because it's too cool to keep
to myself.

First, you can view the entire thing here:
https://github.com/PerlDancer/Dancer2/commit/6eaa6a8136ad26c76a40c3aef49d86310e4474e1

But you probably don't want to. Why? Here's the summary:
6 files changed, 2659 insertions(+), 1236 deletions(-).

Why? Well... let me tell you what she did. She completely restructured the
Manual and Cookbook. This included deciding what should go where, make it
reachable from Dancer2.pm (what's rendered when you open up Dancer2 in
MetaCPAN or perldoc), and structure it within those documents in a coherent
manner.

The Manual now covers:
* Installation
* Bootstrapping
* How to use Dancer2, including:
  - The HTTP methods (including multi-methods)
  - All route definitions
  - Prefixes
  - Hooks
  - Handlers
  - Errors
  - Sessions
  - Templates
  - Static files
  - File uploads
  - Configuration
  - Logging
* How to test Dancer2
* How to package Dancer2, currently covering:
  - Carton
  - FatPacker
  (but more will be added)
* How to add middlewares
* Plugins
And of course,
* DSL keyword index

The Manual is now a proper Manual, explaining how Dancer should be used,
which we could continue to expand so it covers explanations on any and all
keywords as part of a guide you can read. You will still have the DSL
keywords (which many of us jump for when we want to find a keyword quickly)
as well, which we will slowly be using to point to the parts in the Manual
which cover the keyword's usage.

The Cookbook now covers tricks and hints:
* Splitting your application with prefix
* Using auto_page (AutoPage itself covered in the Manual - here is only a
tip to use it)
* Delivering custom error pages
* Using DBIx::Class
* Authentication
* Example for a REST application
* Recommendations on serializers
* Turning off warnings (under "Non-standard" :)
* etc.

If there's a tip you give others, or a pattern you found useful, this is
where you could submit it so others could enjoy. It would fall under "cool
stuff", rather than "the design of the framework". One describes the pieces
and how they interact. The other all the cool stuff you could do with them.

The Deployment document (which existed in 1 and was merged into the
Cookbook at 2 - not the right thing) is now its own separate document,
includes everything in Dancer 1 and adds more:
* Running as CGI or FastCGI
* Running on Perl web servers
* Using different service utilities (daemontools, Ubic, etc.)
* Under a reverse proxy
* From Apache or Lighttpd

This is where we gather the knowledge of everyone deploying Dancer2 in
various environments to make sure we have clear and useful instructions for
the next person who wants to follow the same deployment pattern, and to
offer examples of how you could deploy your Dancer2 applications.

The main module, Dancer2, now links to all of these so they are easily
accessible. The DSL keyword index, since it is useful, is linked separately
of the Manual, so we could find it much more quickly. This is something
that nagged me personally. I never remembered *where* it was documented,
and now, even though it's the proper place, I don't have to remember.
Perldoc Dancer2 and it's there.

I'd like to thank Snigdha for all the work she's done on this. It was not
easy and included a lot of research before she could even begin reading the
Dancer documents, comparing the changes between 1 and 2, making decisions
about the structure, and moving everything inch by inch. (There actually
were a lot of commits, but I did squashed some commits together.)

Have a great day,
S.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.preshweb.co.uk/pipermail/dancer-users/attachments/20150206/508723c0/attachment.html>