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

[Daniel Perrett]

I was looking at the D2 documentation the other day, having trouble following them and I was going to put a request of some sort in in – but, from the description below, it looks like the things that I was going to moan about have been addressed – so thankyou Snigdha!

Daniel

From: dancer-users [mailto:dancer-users-bounces at dancer.pm] On Behalf Of Sawyer X
Sent: 06 February 2015 14:56
To: Perl Dancer users mailing list
Subject: [dancer-users] Snigdha Dagar's (our OPW participant) work has been merged!

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/fe9d1200/attachment-0001.html>