Implement recipes

[daveaglick]

Recipes should configure one or more pipelines. They should be contained in separate libraries and available via NuGet. Therefore, any interfaces need to go in Wyam.Abstractions.

They should also allow additional configuration as needed. Consider how they'll be configured from the command line.

[daveaglick]

Some thoughts:

• Like modules, recipes should implement a specific interface and can be placed in an arbitrary library or in a NuGet package.
• They should be specified on the command-line (with something like a --recipe flag) - the goal is to be able to use recipes with zero configuration
  • The name given in the flag should first be checked to see if there's a recipe with that name in the core library that implements the required interface (--recipe Blog)
  • Then, any referenced libraries should be searched (to support this, a command line equivalent of adding NuGet packages and assemblies similar to the config file should be added if not already available) - something like --nuget Wyam.Recipe.Blog --recipe Blog for recipes in NuGet packages and --assembly Wyam.Recipe.Blog --recipe Blog for recipes in assemblies
  • Note that this might require adding the --nuget and --assembly command line flags, which would work just like the config file and don't directly have anything to do with recipes other than downloading/referencing the package/assembly that the recipe is in
• The recipe interface should be executed before anything else and should initialize the engine with modules, etc. Then, if a config file exists or is specified, it should also be evaluated against the pre-configured engine. That way, the recipe can be fine-tuned by adding pipelines, adjusting modules, etc. if needed.

[daveaglick]

Consider making scaffolding methods a fundamental aspect of recipes. For example, if you create a recipe for a certain type of blog, then you also need to create the scaffolding logic for that recipe. This would make it easier to get up and running quickly with recipies. It would also make it easier to write things like VS templates or Yeoman generators later (though Yeoman is JS-based so it's not clear how we would take advantage of .NET-based scaffolding logic - maybe be calling an intermediate .exe or something).

[daveaglick]

Some recipe ideas:

• Blog
• Docs
• Presentation (output to PPT, PDF, and HTML)
• Resume (output to PDF and HTML)
• Snowfall (highly stylized one-page HTML)

[daveaglick]

When specifying a recipe on the CLI, we want to avoid explicitly loading NuGet packages if possible. One way around this might be to check the loaded packages for the recipe, and if it's not found, try downloading a package with the name Wyam.Recipes.Foo. I.e., this command:

wyam --nuget Wyam.Recipes.Foo --recipe Foo

would be equivalent to:

wyam --recipe Foo

The trick will be in the timing. For this to work, we'd need to load NuGet packages, check for the recipe, then check/load another NuGet package, the try the recipe again.

[LokiMidgard]

Could a recipe also be part of a package that holds something other? In that case maybe saying it should named Wyam.Recpies.Something could be problematic. (Like in #295)

[LokiMidgard]

Just a random thought. I think it is to complicated, but maybe someone could make it better.

We could add some kind of directory to look up different recipes. Wyam would have some kind of standard directory with the standard recipes. this directory maps every recipe to an nuget package where it can be found.

The user could also specify his own directories. We could implement a directory just as an website that hosts some json. Maybe wyam.io could be the default. Another possibility would be to pack it in a nuget package using some kind of interface, maybe utilizing MEF. In the later case the standard could be included in wyam core or a package that is referenced by wyam.all.

Usage would be

wyam --recipe Foo

which would search the installed packages then the standard directory for Foo, downloads its package if needed and then create stuff.

wyam --recipe Foo --recipeDirectory (www.mydonain.net/wyamdiectory | myNuGetDirectoryPacakge)

which would search the installed packages, then the provided directory and if nothing found the standard directory for Foo, downloads its package and then create stuff.

[daveaglick]

Could a recipe also be part of a package that holds something other?

Yep, or more likely there is a recipe-centric module or bit of functionality that someone wants to use even if they don't want the whole recipe. Recipe packages are also going to be a sort of meta-package that include dependencies to other module packages. For example, the blog recipe package is going to reference Wyam.Yaml, Wyam.Markdown, Wyam.Razor, etc. Fetching the recipe package could be a convenient way to get a pre-defined set of module references without having to explicitly include each one.

In that case maybe saying it should named Wyam.Recpies.Something could be problematic.

Right on. In fact, the first recipe package I've started to work on is called Wyam.Blog.

We could add some kind of directory to look up different recipes.

You mean like this:
https://github.com/Wyamio/Wyam/blob/recipes/src/Wyam.Configuration/Configurator.cs#L22
;)

The goal is to be able to do -recipe blog and have the correct NuGet package get implicitly downloaded. I considered automatically just fetching Wyam.* for whatever the recipe name was, but that seemed a little limiting if we end up with multiple similar recipes in the same package, for example.

We could implement a directory just as an website that hosts some json...

I had actually gone down this thought path too - great minds think alike :). The Wyam site would be a good place for it, or I had also considered putting it in a gist or in a file on the repo and fetching from GitHub.

After thinking about it though, I'm not sure there's a ton of benefit there. Most recipes are going to be "official", as most modules are now. Keeping the lookup in the code shouldn't be any more trouble than keeping it on the site, and will make lookups much faster since there won't be a web request involved. I may eventually auto-generate this lookup using some sort of code generation (I.e., scan the solution for recipes at compile time and then generate the lookup table), but the static works for now.

As for user-specified directories, it'll probably be rare that someone creates an entire recipe just for internal use and doesn't contribute it (of course it could happen, just not sure how often). Even if that does happen, it'll probably be a one-off at which point adding the NuGet package that contains the recipe isn't any more trouble than pointing to a directory. I just don't see a situation when someone has a set of non-official recipes that warrants a whole extra directory.

All great thoughts - keep them coming!

[daveaglick]

Recipe support is now in the develop branch. At this point, just have to write the actual recipes and themes...