Add steps to couscous.yml

[elijahb]

I was checking out how to add new functionality (in this case to parse an API Blueprint md file), and while it seemed really easy to add a new step for this, as far as I see I should modify Application/config.php to add this new step (if there is a way to add it to the yml file, is not in the docs).

So to make it really extensible, I think it should be possible to add steps to the yml file, then anyone could write a couscous package step and just use it.

[bobmulder]

This is very interesting. I've discussed this with Matthieu before but he argumented that couscous should be complete enough (please ask him to explain it clear ;)).

However, in your situation it would be very very helpful. I would like to think about a way to realize it...

I understand you wrote something to document APIs? Can you share your code via Gist? I am very interested!!!!

[wysow]

Yes this idea seems interesting for me too, but I also understand @mnapoli point of view, so maybe a solution could be to allow Couscous to be extended by external dependencies...

Anyway, @elijahb if you managed to use Couscous to document an API, like @bobmulder I would appreciate if you can share some ressources... ;)

[mnapoli]

Hi! To sum up the current status on Couscous internal architecture:

• it was meant to work as modules where each module can add new steps
• external modules could be registered and thus extend Couscous

What I came to realize is that it's super hard to manage the order of the steps. E.g. imagine you add your "Blueprint step", where do you add it in the list? At the beginning, end, middle (if so then where in the middle?). All those dependencies between steps are very hard to handle… In fa3e5d2 I had to put back all the steps into one big list so that I could maintain the order better (and because until now there was no actual benefit so it was just a pain).

Now I'm not against offering plugin/module support like you suggest, but those problems must be solved. I've only found poor alternative ideas until now (e.g. events…).

As mentioned by @bobmulder, one reason I don't spend time on this is because I would rather have Couscous work great for what it's supposed to do (i.e. have more built-in features like #120, #39, …), then later think of having 3rd party extensions (and even then I usually work on what I need when I need it). But that's just my preference on how to spend my time, if one of you want to spend time on this feature (and maintain it) I'd be happy.

[wysow]

Humm... I'm thinking about a "quick and not so dirty solution" for this, what about using a yml file to handle the correct list of steps, and import it in the config.php file, using a default file if no custom is set (like steps.yml and steps.default.yml)? Or using the default configuration file...

Maybe I do not see what could be the problems about doing this... What do you think about this guys?

[mnapoli]

If users are forced to redefine the complete list of steps (for example in their couscous.yml or other file in their repo) then there is a high chance it will not be kept in sync when Couscous has more steps/features.

[wysow]

Yes you're right so maybe using a merge mechanism between the 2 files?

[bobmulder]

What about this in your couscous.yml:

extensions:
    - before
        - your/custom/class/or/whatever
    - after
        - your/other/custom/class

We could make multiple callbacks instead of before and after only...

[mnapoli]

That's what there used to be (see the commits I linked) but it's more complicated than that: for example you can't process markdown files if they haven't been loaded yet, but you can't process them after they've been converted to HTML. And then after that they are dumped to disk.

[elijahb]

Ok, I see I opened a big issue here (everything always seems easier at first).

@bobmulder I did not create it, there is a (work-in-progress) standard http://apiblueprint.org to write RESTful API's in markdown. They already have a cli command that converts that to JSON, and there is also a PHP wrapper. So my idea was to write a step that would load that JSON as the metadata to use it afterwards in a template. But I also saw another ideas here among the issues that would be nice to implement as extensions.

What if inside the yml you just add the packages (as classes), and the package itself tells (adding another method like getRunAfterStep to the step interface, that returns the class name) which step it requires before. So you would only have to make a foreach getting the packages, check that method, and insert the new step in the right position inside the default steps list array, and then run as always.

[bobmulder]

(@elijahb) To support manual steps I have created events today: see #150