-
Notifications
You must be signed in to change notification settings - Fork 122
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Align sourceDirectory with the Gradle plugin #254
Comments
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. |
Taking the opportunity to discuss the outputDir also here, I don't think we need changes.
|
Gradle makes this an option via
That might be good for simple cases where the settings are all shared. I would go with the attribute name |
I like that, I will include it.
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. |
Just an implementation note: backend folder should take into account special characters. Check |
I do even consider |
|
It is, because we only do |
Ah, I see what you are saying. The idea behind 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. |
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. |
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? Strictly speaking if you add your asciidoc file to the Maven site, they should go to |
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. |
Your reasoning is safe and sound. Always keep in mind that there is no hard rule. |
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 is not that clear, in particular because when you use maven or gradle you tend to:
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. |
This is not a defensible point. It's highly subjective.
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. |
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. |
@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. |
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
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. |
If that's feasible, I agree it's a great solution. Auto-detect. |
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 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 |
I really would opt for |
@michael-o Would it be un-maven for a person to override the default location? |
@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. |
@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. |
I still consider |
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. |
…fallbacks to 'src/asciidoc' and 'src/main/asciidoc' if not found
…fallbacks to 'src/asciidoc' and 'src/main/asciidoc' if not found
…fallbacks to 'src/asciidoc' and 'src/main/asciidoc' if not found
As proposed by @mojavelinux (twitter) and here (asciidoctor-gradle-plugin/issues/108), the sourceDirectory should be
src/docs/asciidoc
as opposed tosrc/main/asciidoc
.The text was updated successfully, but these errors were encountered: