You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@sling.apache.org by Stefan Seifert <ss...@pro-vision.de> on 2017/03/10 00:25:32 UTC
Maven plugin documentation
for a long time we manually maintained documentation of our maven plugins in the sling site, which is tedious and error-prone.
inspired by the process used by the felix maven-bundle-plugin i've set up the same for the three most important sling plugins:
- maven-sling-plugin [1]
- htl-maven-plugin [2]
- slingstart-maven-plugin [3]
i've also updated the release management documentation [4] - everyone publishing a new release of a maven plugin should update the site as well. although it involves some manual steps it's quite easy and straightforward.
the new section /components [5] on the site is excluded from the normal site publishing process and is only updated when publishing a new maven site (same as in felix). the folder also contains the archived documentations of the old plugins. whe might use the same concept for publishing the Sling API in the future as well. the concept is taken from [6].
stefan
[1] http://sling.apache.org/components/maven-sling-plugin/plugin-info.html
[2] http://sling.apache.org/components/htl-maven-plugin/plugin-info.html
[3] http://sling.apache.org/components/slingstart-maven-plugin/plugin-info.html
[4] http://sling.apache.org/documentation/development/release-management.html#appendix-d-deploy-maven-plugin-documentation
[5] http://sling.apache.org/components
[6] http://maven.apache.org/developers/website/deploy-component-reference-documentation.html
Re: Maven plugin documentation
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Fri, Mar 10, 2017 at 9:58 AM, Stefan Seifert <ss...@pro-vision.de> wrote:
> Bertrand wrote:
>>Also, now when publishing the site via Apache CMS,
>>https://cms.apache.org/sling/publish?diff=1 shows lots of removed
>>files...
> ...I detected that in felix-site a file 'content/extpaths.txt' exists which exactly
> defines this folder as "externall controlled" and keeps it intact on cms publishing...
Ok, I have created https://issues.apache.org/jira/browse/INFRA-13644 about this.
-Bertrand
RE: Maven plugin documentation
Posted by Stefan Seifert <ss...@pro-vision.de>.
>On Fri, Mar 10, 2017 at 9:58 AM, Stefan Seifert <ss...@pro-vision.de>
>wrote:
>> ...step 4 and 5 are not correct currently...
>
>I have restored your previous steps 4. and 5. , should be ok now at
>http://sling.apache.org/documentation/development/release-management.html
>
>-Bertrand
thanks!
stefan
Re: Maven plugin documentation
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Fri, Mar 10, 2017 at 9:58 AM, Stefan Seifert <ss...@pro-vision.de> wrote:
> ...step 4 and 5 are not correct currently...
I have restored your previous steps 4. and 5. , should be ok now at
http://sling.apache.org/documentation/development/release-management.html
-Bertrand
Re: Maven plugin documentation
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Fri, Mar 10, 2017 at 9:58 AM, Stefan Seifert <ss...@pro-vision.de> wrote:
> ...step 4 and 5 are not correct currently.
> the 'scm-publish:publish-scm' goal directly commits the generated documentation to a path
> https://svn.apache.org/repos/infra/websites/production/sling/content/component/<plugin-name>-archives/<plugin-name>-LATEST..
argh...so that's why my test was committed there ;-)
I'll fix that and the documentation now.
-Bertrand
RE: Maven plugin documentation
Posted by Stefan Seifert <ss...@pro-vision.de>.
>I have slightly reworded the instructions at the end of
>http://sling.apache.org/documentation/development/release-management.html
>, could you cross-check?
step 4 and 5 are not correct currently.
the 'scm-publish:publish-scm' goal directly commits the generated documentation to a path
https://svn.apache.org/repos/infra/websites/production/sling/content/component/<plugin-name>-archives/<plugin-name>-LATEST
so it's already in svn, and from there it has to be renamed (or moved) to '<plugin-name>-archives/<plugin-name>-<version>' *and* to a folder '<plugin-name>' (which already exists with the old docs, so the old has to be removed first resulting in a replace). the site html should not be svn-imported again, because then it's duplicated in the svn history. the process is described here [1]. i do not know why the publish-scm plugin does not do this steps automatically.
the other changes are fine.
>Also, now when publishing the site via Apache CMS,
>https://cms.apache.org/sling/publish?diff=1 shows lots of removed
>files under content/components/htl-maven-plugin (probably the whole
>folder), could that be related to what you did?
>
>http://sling.apache.org/components/ looks ok to me, the
>htl-maven-plugin folder is still there after CMS publishing - but this
>makes the publish diff unusable. I can have a closer look but maybe
>you understand what happened based on your changes?
this is strange, not sure why this happens.
when starting testing the publication of the documtation I had the problem that new updates to the cms site completely removed the "components" folder. then I detected that in felix-site a file 'content/extpaths.txt' exists which exactly defines this folder as "externall controlled" and keeps it intact on cms publishing. so there is no longer a conflict and i thought all is fine. i have no idea what the effect on this diff view is. it is happing on felix site as well [2]. unfortunately i have no deeper knowledge on this svn-based cms publishing features.
stefan
[1] http://maven.apache.org/developers/website/deploy-component-reference-documentation.html
[2] https://cms.apache.org/felix/publish?diff=1
Re: Maven plugin documentation
Posted by Bertrand Delacretaz <bd...@apache.org>.
Hi Stefan,
On Fri, Mar 10, 2017 at 1:25 AM, Stefan Seifert <ss...@pro-vision.de> wrote:
> ...inspired by the process used by the felix maven-bundle-plugin i've set up the same for the three most important sling plugins...
Great, thanks for this!
I have slightly reworded the instructions at the end of
http://sling.apache.org/documentation/development/release-management.html
, could you cross-check?
Also, now when publishing the site via Apache CMS,
https://cms.apache.org/sling/publish?diff=1 shows lots of removed
files under content/components/htl-maven-plugin (probably the whole
folder), could that be related to what you did?
http://sling.apache.org/components/ looks ok to me, the
htl-maven-plugin folder is still there after CMS publishing - but this
makes the publish diff unusable. I can have a closer look but maybe
you understand what happened based on your changes?
-Bertrand
Re: Maven plugin documentation
Posted by Robert Munteanu <ro...@apache.org>.
On Fri, 2017-03-10 at 00:25 +0000, Stefan Seifert wrote:
> for a long time we manually maintained documentation of our maven
> plugins in the sling site, which is tedious and error-prone.
>
> inspired by the process used by the felix maven-bundle-plugin i've
> set up the same for the three most important sling plugins:
> - maven-sling-plugin [1]
> - htl-maven-plugin [2]
> - slingstart-maven-plugin [3]
(snip)
Looks great, thanks for setting this up.
Robert
Re: Maven plugin documentation
Posted by Konrad Windszus <ko...@gmx.de>.
I was assuming that the official Apache Maven Plugins publish snapshot versions as well, but this is not the case (https://svn.apache.org/repos/infra/websites/production/maven/components/). So probably this is not a good idea at all.
> On 13 Mar 2017, at 13:22, Stefan Seifert <ss...@pro-vision.de> wrote:
>
> do we want to deploy SNASPHOT sites? just for a review you can do a local "mvn site" on the plugin project to see the same results.
>
> technically it would be easy using the "scm-publish:publish-scm" goal - but it always creates a new history entry in the SVN of the site and seems more intended to be used only for the final docs.
>
> stefan
>
>
>> -----Original Message-----
>> From: Konrad Windszus [mailto:konrad_w@gmx.de]
>> Sent: Monday, March 13, 2017 1:02 PM
>> To: dev@sling.apache.org
>> Subject: Re: Maven plugin documentation
>>
>> Hi Stefan,
>> thanks a lot for your efforts.
>> Can we also add a hint on how to deploy a SNAPSHOT site (e.g. for others to
>> review?)
>> Thanks,
>> Konrad
>>> On 10 Mar 2017, at 01:25, Stefan Seifert <ss...@pro-vision.de> wrote:
>>>
>>> for a long time we manually maintained documentation of our maven plugins
>> in the sling site, which is tedious and error-prone.
>>>
>>> inspired by the process used by the felix maven-bundle-plugin i've set up
>> the same for the three most important sling plugins:
>>> - maven-sling-plugin [1]
>>> - htl-maven-plugin [2]
>>> - slingstart-maven-plugin [3]
>>>
>>> i've also updated the release management documentation [4] - everyone
>> publishing a new release of a maven plugin should update the site as well.
>> although it involves some manual steps it's quite easy and straightforward.
>>>
>>> the new section /components [5] on the site is excluded from the normal
>> site publishing process and is only updated when publishing a new maven
>> site (same as in felix). the folder also contains the archived
>> documentations of the old plugins. whe might use the same concept for
>> publishing the Sling API in the future as well. the concept is taken from
>> [6].
>>>
>>> stefan
>>>
>>> [1] http://sling.apache.org/components/maven-sling-plugin/plugin-
>> info.html
>>> [2] http://sling.apache.org/components/htl-maven-plugin/plugin-info.html
>>> [3] http://sling.apache.org/components/slingstart-maven-plugin/plugin-
>> info.html
>>> [4] http://sling.apache.org/documentation/development/release-
>> management.html#appendix-d-deploy-maven-plugin-documentation
>>> [5] http://sling.apache.org/components
>>> [6] http://maven.apache.org/developers/website/deploy-component-
>> reference-documentation.html
>>>
>>>
>>
>
>
RE: Maven plugin documentation
Posted by Stefan Seifert <ss...@pro-vision.de>.
do we want to deploy SNASPHOT sites? just for a review you can do a local "mvn site" on the plugin project to see the same results.
technically it would be easy using the "scm-publish:publish-scm" goal - but it always creates a new history entry in the SVN of the site and seems more intended to be used only for the final docs.
stefan
>-----Original Message-----
>From: Konrad Windszus [mailto:konrad_w@gmx.de]
>Sent: Monday, March 13, 2017 1:02 PM
>To: dev@sling.apache.org
>Subject: Re: Maven plugin documentation
>
>Hi Stefan,
>thanks a lot for your efforts.
>Can we also add a hint on how to deploy a SNAPSHOT site (e.g. for others to
>review?)
>Thanks,
>Konrad
>> On 10 Mar 2017, at 01:25, Stefan Seifert <ss...@pro-vision.de> wrote:
>>
>> for a long time we manually maintained documentation of our maven plugins
>in the sling site, which is tedious and error-prone.
>>
>> inspired by the process used by the felix maven-bundle-plugin i've set up
>the same for the three most important sling plugins:
>> - maven-sling-plugin [1]
>> - htl-maven-plugin [2]
>> - slingstart-maven-plugin [3]
>>
>> i've also updated the release management documentation [4] - everyone
>publishing a new release of a maven plugin should update the site as well.
>although it involves some manual steps it's quite easy and straightforward.
>>
>> the new section /components [5] on the site is excluded from the normal
>site publishing process and is only updated when publishing a new maven
>site (same as in felix). the folder also contains the archived
>documentations of the old plugins. whe might use the same concept for
>publishing the Sling API in the future as well. the concept is taken from
>[6].
>>
>> stefan
>>
>> [1] http://sling.apache.org/components/maven-sling-plugin/plugin-
>info.html
>> [2] http://sling.apache.org/components/htl-maven-plugin/plugin-info.html
>> [3] http://sling.apache.org/components/slingstart-maven-plugin/plugin-
>info.html
>> [4] http://sling.apache.org/documentation/development/release-
>management.html#appendix-d-deploy-maven-plugin-documentation
>> [5] http://sling.apache.org/components
>> [6] http://maven.apache.org/developers/website/deploy-component-
>reference-documentation.html
>>
>>
>
Re: Maven plugin documentation
Posted by Konrad Windszus <ko...@gmx.de>.
Hi Stefan,
thanks a lot for your efforts.
Can we also add a hint on how to deploy a SNAPSHOT site (e.g. for others to review?)
Thanks,
Konrad
> On 10 Mar 2017, at 01:25, Stefan Seifert <ss...@pro-vision.de> wrote:
>
> for a long time we manually maintained documentation of our maven plugins in the sling site, which is tedious and error-prone.
>
> inspired by the process used by the felix maven-bundle-plugin i've set up the same for the three most important sling plugins:
> - maven-sling-plugin [1]
> - htl-maven-plugin [2]
> - slingstart-maven-plugin [3]
>
> i've also updated the release management documentation [4] - everyone publishing a new release of a maven plugin should update the site as well. although it involves some manual steps it's quite easy and straightforward.
>
> the new section /components [5] on the site is excluded from the normal site publishing process and is only updated when publishing a new maven site (same as in felix). the folder also contains the archived documentations of the old plugins. whe might use the same concept for publishing the Sling API in the future as well. the concept is taken from [6].
>
> stefan
>
> [1] http://sling.apache.org/components/maven-sling-plugin/plugin-info.html
> [2] http://sling.apache.org/components/htl-maven-plugin/plugin-info.html
> [3] http://sling.apache.org/components/slingstart-maven-plugin/plugin-info.html
> [4] http://sling.apache.org/documentation/development/release-management.html#appendix-d-deploy-maven-plugin-documentation
> [5] http://sling.apache.org/components
> [6] http://maven.apache.org/developers/website/deploy-component-reference-documentation.html
>
>