Align sourceDirectory with the Gradle plugin

[abelsromero]

As proposed by @mojavelinux (twitter) and here (asciidoctor-gradle-plugin/issues/108), the sourceDirectory should be src/docs/asciidoc as opposed to src/main/asciidoc.

[mojavelinux]

My understanding was always that "main" referred to "main application source code". It's clear that docs are not part of the main application source code, which is why I much prefer that we use "docs" as the category.

[abelsromero]

Taking the opportunity to discuss the outputDir also here, I don't think we need changes.
Maybe two things:

• consider creating an output folder for the backend, but I don't think it's useful here. backend is a single value in the Maven plugin, so users wanting several renderizations need to add a maven execution. That makes them aware they should set a different outputDir.
• should we make backend a List? not sure really but I'd rather stay with the current model, makes the XML configuration simpler for most cases.

[mojavelinux]

consider creating an output folder for the backend

Gradle makes this an option via separateOutputDirs. I've used it on occasion.

should we make backend a List?

That might be good for simple cases where the settings are all shared. I would go with the attribute name backends though, we would be mutually exclusive with backend.

[abelsromero]

Gradle makes this an option via separateOutputDirs. I've used it on occasion.

I like that, I will include it.

That might be good for simple cases where the settings are all shared. I would go with the attribute name backends though, we would be mutually exclusive with backend.

It's not elegant but I like it, we can add an new List attribute that override the other of if set. That way we don't break compatibility.

[abelsromero]

Just an implementation note: backend folder should take into account special characters. Check toSafeFileName in Gradle API.
https://github.com/asciidoctor/asciidoctor-gradle-plugin/blob/development/src/main/groovy/org/asciidoctor/gradle/AsciidoctorTask.groovy#L611

[michael-o]

I do even consider /docs/ superfluous, it can simply be src/asciidoc. Moreover, src/main/asciidoc doesn't make sense too because there won't be any test asciidocs in general.

[mojavelinux]

src/asciidoc would not be consistent with Maven conventions.

[michael-o]

It is, because we only do src/site. There is no split here. No main site and no test site. Same applies for asciidoc. With src/main/asciidocyou are implying that there is a potential test asciidoc. This is the view I share as a Maven PMC.

[mojavelinux]

Ah, I see what you are saying.

The idea behind src/docs is that asciidoc isn't the only documentation language. This is consistent with the src/*/java and src/*/groovy split. In other words, src because Maven. docs as the category (to differentiate from code folders). And asciidoc as the language.

I've always interpreted "main" not to mean "not test", but rather to mean "is application code". If we don't do that, then we put "application code" next to a language-specific folder, which seems incorrect. But perhaps I'm not understanding the logic behind the hierarchy correctly.

[mojavelinux]

I don't really care that much about the hierarchy. I'm just trying to be consistent with what Maven does so that users know what to expect. My instinct was src/docs/asciidoc based on all the years of using Maven. I suspect other users will share that instinct...or perhaps they won't.

[michael-o]

There is no hard rule, we only encourage to do convention over configuration. There is a same case for Maven Assembly Plugin. Where should asm descriptors go? /src/main/assembly or /src/assembly.

Strictly speaking if you add your asciidoc file to the Maven site, they should go to src/site/asciidoc otherwise /src/asciidoc is a good spot. src/docs isn't wrong either, but I highly doubt that people will use n different formats to document a single project.

[mojavelinux]

but I highly doubt that people will use n different formats to document a single project.

you'd be surprised ;0

The other defense of src/docs/asciidoc is that when you have apt pages in site, you use src/site/apt. That's really where I got the original idea for this hierarchy. And since you suggested "src/site/asciidoc", you are only strengthening that argument IMO.

I'm still not convinced src/asciidoc is consistent with any other pattern in Maven. "asciidoc" is not equivalent to "site", so it just doesn't fit in my mind. And src/docs steps on the namespace so you can't possibly have other kinds or formats of docs once you do that.

[michael-o]

Your reasoning is safe and sound. Always keep in mind that there is no hard rule. src/docs/asciidoc is just file. Maybe src/docs/assets would exist.

[rmannibucau]

On the src location, even if probably not highly important, I think main was a very good and natural location so I'll try to justify it a bit:

It's clear that docs are not part of the main application source code, 

It is not that clear, in particular because when you use maven or gradle you tend to:

1. Make it living so it becomes sources of thz module,
2. Deliver it (as war, zip, webjar).

I would add that it is not uncommon to see people using antora to have a sec/main/antora because doc is considered as a prod deliverable of the project.

Also note that src/docs is kind of weird and not a common default - main/{plugin,language} stays the common way from experience even if there are some exceptions.

Last, aligning maven on gradle sounds weird because both build tools kind of don't fully align in terms of conventions, even if java side is pretty close (except in build folder).

So at the end it sounds like a not that fair default + a breaking change not that justifiable in all cases since adoctor 2 does not break much user facing side of things.

[mojavelinux]

It's clear that docs are not part of the main application source code,

This is not a defensible point. It's highly subjective.

Also note that src/docs is kind of weird and not a common default - main/{plugin,language} stays the common way from experience even if there are some exceptions.

As I understand it, dating back to when this granular directory hierarchy was introduced, is that the second segment was supposed to be the purpose. "main" is short for "main application code". "test" is short for "test suite". Therefore, it's perfectly natural for "docs" to be short for "documentation". It fits absolutely perfectly with the original indent of this level. People may have gotten used to overusing "main" for everything that isn't test, but it's simply not in the spirit of the original design. "docs", on the other hand, is.

[mojavelinux]

So at the end it sounds like a not that fair default + a breaking change not that justifiable in all cases since adoctor 2 does not break much user facing side of things.

This part I can agree with. I think we should start encouraging people to migrate to "src/docs/asciidoc" by specifying the override in the POM. Then, once we have most people doing it this way, we can make the switch and require that anyone who didn't follow the advice to add extra configuration.

In other words, if we're going to make this change, we need to make it gently by having a long period to transition.

[rmannibucau]

@mojavelinux I agree with the analyzis of main/test origin but not the conclusion "docs" is "therefore" natural. Doc is prod code - or it is not a doc by definition ;) - so main fits very well regarding that point, in particular since a few years where "main" hosts multiple flavors of the prod code (we become multi cloud more and more). Then "docs" usage never had been natural in maven - was "site" if we get back to the roots. Also note that javadoc uses src/main/javadoc.

Finally I have a doubt about a "long transition period" which - from my past experience - means nobody - a few - will switch so it just delays the issue which at the end will bring a migration drawback and no feature or gain on the user land.

What about supporting both - multiple - OOTB? It is trivial in the plugin and enables to makes everyone happy probably.

[mojavelinux]

Doc is prod code - or it is not a doc by definition

Docs is not prod code, at least not in the sense of it being part of the application. It certainly supports the prod code, so it's its own type of prod. But to mix it with main is simply incorrect. I don't agree main fits here.

In the end, it doesn't matter all the much to me. My goal is not to win this argument. It just frustrates me that Maven went through the trouble of introducing a standard directory hierarchy and then really didn't make use of it. We would have been better off with flat directories (like docs) if that was going to be the result. If src is mostly meaningless, and tremendous confusion around the meaning of main, I'd be even okay with docs/asciidoc.

Finally I have a doubt about a "long transition period" which - from my past experience - means nobody - a few - will switch so it just delays the issue which at the end will bring a migration drawback and no feature or gain on the user land.

Not if you provide a clear announcement and a time limit. If you don't comply, it's your own fault. If that means that at the deadline only 10% migrated, then they invited the pain on themselves. The project can't be to blame.

[mojavelinux]

What about supporting both - multiple - OOTB? It is trivial in the plugin and enables to makes everyone happy probably.

If that's feasible, I agree it's a great solution. Auto-detect.

[ysb33r]

I had a conversation with @hboutemy today - really great to sit down with someone who really knows quite a bit about Maven. He also explained to me about how src/site uses Asciidoctor and that that effectively is irrelevant to the use of the asciidoctor-maven-plugin .

Basically as long as you don't touch any of the two Doxia files that affects site, you can rename the asciidoc source code directory to whatever. So I would recommend to go with with src/docs/asciidoc and then faill back (with a warning) to src/main/asciidoc.

[michael-o]

I really would opt for src/asciidoc. We, the Maven developers, have never established something like src/docs. I would treat asciidoc as opaque source code like everything else, just like src/assembly with maven-assembly-plugin.

[ysb33r]

@michael-o Would it be un-maven for a person to override the default location?

[rmannibucau]

@ysb33r convention over configuration ;) + more on a generic user side of things it is not justifiable so it looks more and more like a lost-lost.

[michael-o]

@ysb33r What you do in your POM is actually your business as long as it does not deviate too much from the convention. If you use Maven like Ant then you really should use Ant. The discussion here is about sensisble defaults.

[michael-o]

I still consider src/asciidoc to be the best option. This is what I do use throughout all projects.

[abelsromero]

I want to tackle this for the next release. Supporting multi-path is absolutely trivial and would make the change smooth by supporting the current path.
So, the plugin will set as default src/docs/asciidoc and if not found, will fallback for src/asciidoc and then src/main/asciidoc, in that order.