Adds publisher option to jbake

[lordofthejars]

With this pull request jbake users can create their own publishers modules so after a site is baked can be published automatically.

Currently a Github publisher has been implemented but users can implement their own by using the jbake spi.

Also JDK has been updated to Java 7 to be able to use Java IO features developed on that version of java.

[vietj]

This is a very nice feature, however sometimes the github branch can be something else than "gh-pages" . For instance it can be the "master" branch for a site like jbake-org.github.io . This PR has the "gh-pages" branch hardcoded, can you make it more configurable to address non "gh-pages" branches ?

[lordofthejars]

Yes this is true, but I am not sure (of course maybe I am wrong) that this is the kind of scenario that one user of jbake will use in most of situations. For example I have always seen that people have the master branch for the sources and the gh-pages for the autogenerated pages, because jbake autogenerate pages from sources, it seems logical that master branch will be the one where you will save your sources, and then the published branch where you render and serve the rendered pages. With the approach you are mention it seems that the sources are not saved so you use github as only web page server, which of course it is still valid.

The good news is that this pull request not only contains the github (gh-pages) publisher but also an spi so everyone can implement its own publisher. So what you are explaining it is still possible for jbake, but I suggest that because we have an spi, instead of making publishers huge with different options (which some of them a deep impact on the implementation), create another publisher which can be called OrganizationSiteGithubPublisher that basically converts the output directory into git repo (in case of gh-pages git repo is the root of the project), and pushes the change to master. If you look my code you will see that it is not a simply matter of passing a different branch name because of orphan branches. Of course it is not impossible to adapt both strategies into one publisher, but in my opinion it will become a bit more complicated to maintain.

WDYT?

[volyx]

Maybe, if user didn't configure his branch's properties "GithubPublisher" will use default strategy?

[lordofthejars]

Yes it is a possibility but if for example 80% of users want to release to gh-pages then you are forcing them to set branch name every time, maybe an special parameter Can be used

Enviat des del meu iPhone

El 25/05/2014, a les 12.33, volyihin [email protected] va escriure:

Maybe, if user didn't configure his branch's properties "GithubPublisher" will use default strategy?

—
Reply to this email directly or view it on GitHub.

[volyx]

I mean if user will specify custom parameters - use their, if not - release to gh-pages(default parameters, hardcoded)

[lordofthejars]

Well both approaches have their pros and cons WDYT Johnattan?

Enviat des del meu iPhone

El 25/05/2014, a les 13.32, volyihin [email protected] va escriure:

I mean if user will specify custom parameters - use their, if not - release to gh-pages(default parameters, hardcoded)

—
Reply to this email directly or view it on GitHub.

[vietj]

I am using mainly jbake for what GitHub calls "user or organization" site and in this configuration, the master branch is used (unless it can be configured but I did not find the option). For "project" site, the "gh-pages" branch is used. For instance https://github.com/crashub/crashub.github.com

It makes sense to address both use case, and have "gh-pages" to be the default. The maven plugin then could expose this option somehow.

[jonbullock]

First off, thanks for the contribution Alex, great work!

Please correct me if I'm wrong here as I've only reviewed the code online so far, but the constants in GithubPublisher could be defined via the configuration system but provide a default either through the default.properties file or even in the class itself in a similar way to here:

https://github.com/jbake-org/jbake/blob/master/src/main/java/org/jbake/parser/AsciidoctorEngine.java#L131

This would enable the feature to just work out of the box for the 80% of users while still allowing the 20% of users to customise as they see fit.

[lordofthejars]

Hello,

the problem is a bit complicated to explain but I will try.

Github acts as a web server in two cases:

• for the gh-pages branch (project site)
• for master branch when the repo is called
  username.github.io(organization site)

In both cases the project should be a git project so where is the problem.

In jbake you have content, configuration, templates directories which can
be seen as source code of the site, and an output directory where the baked
site is rendered. In case you want to use the gh-pages approach it seems
logical that the master branch is where the sources are stored and the
gh-pages branch the baked site. So the root directory must be a git
project. Then when you want to publish one site, what the publisher does is
create an orphan branch called gh-pages and copy the content of output
directory into that branch, and push it to github. This is basically the
project site approach.

So what's happening with organization? It is not as easy as passing to the
publisher that wants to publish to master branch. Why? Because master
branch is the root of the directory, so when we try to create the orphan
branch with name master, it will throw an exception. To deal with this case
what we need is to not create git project in root directory, but in output
directory, so it will be the master and every push go to github master
branch.

So passing as argument the branch name is has not much sense because Github
only supports gh-pages.

So arribed at this point we can consider two approaches:

First one is modify current publisher to something like:

if(projectSite) {

code to project site

} else {
code to organization site
}

But I think (and this is the style of programming) that classes should be
as small as possible, so I would prefer to have to publishers. Moreover we
could have two publishers (one called GithubPublisher) which is used for
Github gh-pages, and another publisher called GitPublisher which uses the
approach of organization site but has the advantage that you can even use
Git as a deployer to any site.

Of course I am also thinking about WarPublisher, FtpPublisher, ... but it
will implement as soon as I require them.

And obviously I have in mind create a plugin extensions for jBake as well,
because I think I will need something like awestruct offers, but this is
another battle.

WDYT?

2014-05-26 23:30 GMT+02:00 Jonathan Bullock [email protected]:

First off, thanks for the contribution Alex, great work!

Please correct me if I'm wrong here as I've only reviewed the code online
so far, but the constants in GithubPublisher could be defined via the
configuration system but provide a default either through the
default.properties file or even in the class itself in a similar way to
here:

https://github.com/jbake-org/jbake/blob/master/src/main/java/org/jbake/parser/AsciidoctorEngine.java#L131

This would enable the feature to just work out of the box for the 80% of
users while still allowing the 20% of users to customise as they see fit.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/113#issuecomment-44219151
.

+----------------------------------------------------------+
Alex Soto Bueno - Computer Engineer
www.lordofthejars.com
+----------------------------------------------------------+

[jonbullock]

Thanks for explaining that Alex, I haven't used GitHub Pages yet myself.

Since you've started the work to be able to add multiple Publishers, the support of User/Org Pages should be straight forward to implement in another class as you've suggested.

[msgilligan]

Personally, I'd rather JBake not add publishing modules. I'm using the Gradle Github Publisher and it seems to me that it makes more sense to use your build tool of choice (e.g. Gradle, Maven, etc) to do the publishing step. I think there will be a greater selection of higher-quality choices that way and JBake can stay focused on core functionality.

[aalmiray]

I agree with @msgilligan. I too use the Gradle Github Publisher. Adding publishing capabilities to jbake might make it overextend its responsibilities. The advantage of having it inside jbake is that any build tool could extend it with custom publishers. OTOH jbake is a site rendering tool (so far).

I feel it for the maven users because the gradle plugin ecosystem is much more fun 😏

[jonbullock]

Thanks for the comments guys. I'm torn about adding this feature, which is why it's been pushed back to v3.0.0, for users who use build systems it does overlap existing functionality available. However, for users who prefer the CLI it would be beneficial. What if this was provided by a plugin/extension instead? Would allow JBake to stay focused on core functionality and this would not then become a consideration in any future development...

[aalmiray]

Pluggable publishing extensions sound like a good compromise to me 😏