API for external applications

[hacdias]

From #1859

New Website:

site := &api.NewSite{}
site.Set("force", "true")
site.Set("path", path)
site.Make()

Build:

build := &api.Build{}
build.Set("source", path)
build.Run()

All of the stuff above was tested.

[hacdias]

Now it passes but I can't understand. The diff is exactly the same @bep

[bep]

2016

[hacdias]

Changed @bep

[bep]

One of my thoughts with an API was to limit it somehow to what the external tools needs. I know this is hard with the current setup, but if you limit it to the hugoCmd (for starters), you could name this func Build() or something. Then it also would be possible to create a more natural API than the CLI flags.

[hacdias]

@bep Sure, you're right. Let's start with something simple, but it can be improved in the near future. The api could be also extended for the other commands, for example. Like api.New(path string) to generate a new website!

Relatively to the flags, I'm thinking about it. Some kind of Set function. I can work on that.

[bep]

Wouldn't hugoCmd.ExecuteC() do the trick? Note the C at the end, then you can return an error to the client in case of errors. You would probably have to duplicate parts of commands.Execute -- but it would make a slightly better API.

[hacdias]

@bep that would be a good idea, but to do so I would have to export HugoCmd, wouldn't I?

[hacdias]

What do you think @spf13 @bep?

[spf13]

I'm not entirely clear about the need for this or this approach.

I think the reason for this is so that Hugo can be used more as a library by something like Caddy.

Assuming that is the case then I think we should seriously consider taking one of two approaches.

Approach 1: Cobra Command as API

We already have an API of sorts implemented in the Cobra commands. Instead of redefining every command simply providing a wrapping mechanism that can easily call a command and pass in settings would be very useful. This approach wouldn't be Hugo specific but would be usable by any Cobra app. You've somewhat started this approach.

Approach 2: An API package

This would be a full API which would be used by Hugo Commands as well as any external libraries. We would move most of the code that are in the current commands into these API calls and the Commands package would just be a thin layer wrapping calls to these APIs.

The approach in the current PR is a bit of both of these and I believe that's an incorrect approach.

My gut is that the first approach may be the better one. It would be much simpler and much less disruptive of a change.

There's an argument that we may want things exposed as an API that aren't currently exposed via a Command, but my gut feeling is that we would want to expose them at some point anyway.

Thinking beyond this it could be a really powerful feature of Cobra if as part of the commands you would be defining simultaneously a CLI UI, an programatic API and possibly a REST API.

[bep]

My 50 cent:

• This topic started when I unexported HugoCmd then MainSite causing the Caddy Hugo plugin to break.
• Having a narrow API to 3rd-party clients such as the Caddy plugin means that it is easier to make internal changes without too much worry about breaking stuff.
• Exposing ALL of the Cobra commands in an API wrapper may sound nice and dandy and all, but it will be painful.

[hacdias]

Or we can export the commands. Or isn't that an option?

[bep]

Or we can export the commands. Or isn't that an option?

Which is what we have now. If you export one command you export them all.

[bep]

I think we need to restart this dicsussion. I will close this now.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.