Ivy - we have now moved to asciidoc for docs

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Ivy - we have now moved to asciidoc for docs

J Pai
The documentation for ant-ivy project has now been migrated to asciidoc. The migration used a tool developed by Nicolas to migrate the xooki backed HTML docs to asciidoc. This tool auto-generated the asciidoc text and for most part no other changes were needed. However, there are some fixes the generated asciidoc will need which I’m doing and will continue to do in the coming days to fix any issues with the generated doc. Once the fixes are done, soon, we’ll remove the xooki backed documentation completely from our git repo. For now though, any new documentation or changes should go into the asciidoc files.

-Jaikiran
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

AW: Ivy - we have now moved to asciidoc for docs

Jan Matèrne (jhm)
Doc's mentioning 'how to document' must be updated.
I found http://ant.apache.org/ivy/write-doc.html Some more?

Jan

> -----Ursprüngliche Nachricht-----
> Von: Jaikiran Pai [mailto:[hidden email]]
> Gesendet: Montag, 19. Juni 2017 04:52
> An: Ant Developers List
> Betreff: Ivy - we have now moved to asciidoc for docs
>
> The documentation for ant-ivy project has now been migrated to
> asciidoc. The migration used a tool developed by Nicolas to migrate the
> xooki backed HTML docs to asciidoc. This tool auto-generated the
> asciidoc text and for most part no other changes were needed. However,
> there are some fixes the generated asciidoc will need which I’m doing
> and will continue to do in the coming days to fix any issues with the
> generated doc. Once the fixes are done, soon, we’ll remove the xooki
> backed documentation completely from our git repo. For now though, any
> new documentation or changes should go into the asciidoc files.
>
> -Jaikiran
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email] For additional
> commands, e-mail: [hidden email]



---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy - we have now moved to asciidoc for docs

Nicolas Lalevée
In reply to this post by J Pai

> Le 19 juin 2017 à 04:52, Jaikiran Pai <[hidden email]> a écrit :
>
> The documentation for ant-ivy project has now been migrated to asciidoc. The migration used a tool developed by Nicolas to migrate the xooki backed HTML docs to asciidoc. This tool auto-generated the asciidoc text and for most part no other changes were needed. However, there are some fixes the generated asciidoc will need which I’m doing and will continue to do in the coming days to fix any issues with the generated doc. Once the fixes are done, soon, we’ll remove the xooki backed documentation completely from our git repo. For now though, any new documentation or changes should go into the asciidoc files.

I did a general grep about finding non translated html markup, and I have cleaned the ones I have found.
I have pushed the result here: http://people.apache.org/~hibou/doc/ <http://people.apache.org/~hibou/doc/>

Probably we can start pushing it to the site, since there is section dedicated to the trunk version of the doc (which should be probably renamed master).
http://ant.apache.org/ivy/history/trunk/index.html <http://ant.apache.org/ivy/history/trunk/index.html>
It would be an opportunity to get an idea of what would it mean when a release will happen.

I have noticed one bug in the generation of the toc. There is notion of abstract node, which has a title but no link, it shouldn’t be clickable. But for instance the node at Reference/Introduction is clickable, and sends to the home. This should be fixed. I mentioning it if somebody wants to look at it, before me.

And just an idea: since there are a lot of pages, maybe we could organize a review at many, without useless double checks. I see 4 big parts in the doc: the ant tasks, the pages related to the ivy file, the pages related to the ivysettings, and the other pages. If 4 volunteers can do a quick review of each page, I think we can be pretty confident that we didn’t leave any ugliness somewhere. The goal wouldn’t to do a fine grain review, but ensure that everything is readable. wdyt ?

Nicolas

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy - we have now moved to asciidoc for docs

Nicolas Lalevée
In reply to this post by Jan Matèrne (jhm)

> Le 19 juin 2017 à 08:30, Jan Matèrne (jhm) <[hidden email]> a écrit :
>
> Doc's mentioning 'how to document' must be updated.
> I found http://ant.apache.org/ivy/write-doc.html Some more?

This is the only page which explain xooki I know.

Nicolas

>
> Jan
>
>> -----Ursprüngliche Nachricht-----
>> Von: Jaikiran Pai [mailto:[hidden email]]
>> Gesendet: Montag, 19. Juni 2017 04:52
>> An: Ant Developers List
>> Betreff: Ivy - we have now moved to asciidoc for docs
>>
>> The documentation for ant-ivy project has now been migrated to
>> asciidoc. The migration used a tool developed by Nicolas to migrate the
>> xooki backed HTML docs to asciidoc. This tool auto-generated the
>> asciidoc text and for most part no other changes were needed. However,
>> there are some fixes the generated asciidoc will need which I’m doing
>> and will continue to do in the coming days to fix any issues with the
>> generated doc. Once the fixes are done, soon, we’ll remove the xooki
>> backed documentation completely from our git repo. For now though, any
>> new documentation or changes should go into the asciidoc files.
>>
>> -Jaikiran
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email] For additional
>> commands, e-mail: [hidden email]
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy - we have now moved to asciidoc for docs

Gintautas Grigelionis
SVG is inlined as code, see http://people.apache.org/~hibou/doc/osgi.html

Gintas

2017-06-20 0:09 GMT+02:00 Nicolas Lalevée <[hidden email]>:

>
> > Le 19 juin 2017 à 08:30, Jan Matèrne (jhm) <[hidden email]> a écrit :
> >
> > Doc's mentioning 'how to document' must be updated.
> > I found http://ant.apache.org/ivy/write-doc.html Some more?
>
> This is the only page which explain xooki I know.
>
> Nicolas
>
> >
> > Jan
> >
> >> -----Ursprüngliche Nachricht-----
> >> Von: Jaikiran Pai [mailto:[hidden email]]
> >> Gesendet: Montag, 19. Juni 2017 04:52
> >> An: Ant Developers List
> >> Betreff: Ivy - we have now moved to asciidoc for docs
> >>
> >> The documentation for ant-ivy project has now been migrated to
> >> asciidoc. The migration used a tool developed by Nicolas to migrate the
> >> xooki backed HTML docs to asciidoc. This tool auto-generated the
> >> asciidoc text and for most part no other changes were needed. However,
> >> there are some fixes the generated asciidoc will need which I’m doing
> >> and will continue to do in the coming days to fix any issues with the
> >> generated doc. Once the fixes are done, soon, we’ll remove the xooki
> >> backed documentation completely from our git repo. For now though, any
> >> new documentation or changes should go into the asciidoc files.
> >>
> >> -Jaikiran
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: [hidden email] For additional
> >> commands, e-mail: [hidden email]
> >
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: [hidden email]
> > For additional commands, e-mail: [hidden email]
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy - we have now moved to asciidoc for docs

J Pai
In reply to this post by Nicolas Lalevée
Yes, that appears to be the only place where we explain documentation contribution.

However, the IvyDE project page too points to this page. That’s a reminder for us that the IvyDE project too probably needs to move to asciidoc.

-Jaikiran

On 20-Jun-2017, at 3:39 AM, Nicolas Lalevée <[hidden email]> wrote:


> Le 19 juin 2017 à 08:30, Jan Matèrne (jhm) <[hidden email]> a écrit :
>
> Doc's mentioning 'how to document' must be updated.
> I found http://ant.apache.org/ivy/write-doc.html Some more?

This is the only page which explain xooki I know.

Nicolas

>
> Jan
>
>> -----Ursprüngliche Nachricht-----
>> Von: Jaikiran Pai [mailto:[hidden email]]
>> Gesendet: Montag, 19. Juni 2017 04:52
>> An: Ant Developers List
>> Betreff: Ivy - we have now moved to asciidoc for docs
>>
>> The documentation for ant-ivy project has now been migrated to
>> asciidoc. The migration used a tool developed by Nicolas to migrate the
>> xooki backed HTML docs to asciidoc. This tool auto-generated the
>> asciidoc text and for most part no other changes were needed. However,
>> there are some fixes the generated asciidoc will need which I’m doing
>> and will continue to do in the coming days to fix any issues with the
>> generated doc. Once the fixes are done, soon, we’ll remove the xooki
>> backed documentation completely from our git repo. For now though, any
>> new documentation or changes should go into the asciidoc files.
>>
>> -Jaikiran
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email] For additional
>> commands, e-mail: [hidden email]
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]



---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy - we have now moved to asciidoc for docs

J Pai
In reply to this post by Nicolas Lalevée
>
> On 20-Jun-2017, at 3:38 AM, Nicolas Lalevée <[hidden email]> wrote:
>
>
>> Le 19 juin 2017 à 04:52, Jaikiran Pai <[hidden email]> a écrit :
>>
>> The documentation for ant-ivy project has now been migrated to asciidoc. The migration used a tool developed by Nicolas to migrate the xooki backed HTML docs to asciidoc. This tool auto-generated the asciidoc text and for most part no other changes were needed. However, there are some fixes the generated asciidoc will need which I’m doing and will continue to do in the coming days to fix any issues with the generated doc. Once the fixes are done, soon, we’ll remove the xooki backed documentation completely from our git repo. For now though, any new documentation or changes should go into the asciidoc files.
>
> I did a general grep about finding non translated html markup, and I have cleaned the ones I have found.
> I have pushed the result here: http://people.apache.org/~hibou/doc/ <http://people.apache.org/~hibou/doc/>
>
> Probably we can start pushing it to the site, since there is section dedicated to the trunk version of the doc (which should be probably renamed master).
> http://ant.apache.org/ivy/history/trunk/index.html <http://ant.apache.org/ivy/history/trunk/index.html>
> It would be an opportunity to get an idea of what would it mean when a release will happen.

I actually forgot to send a mail yesterday, but I setup our nightly Ivy job on Jenkins to publish the latest generated docs as build artifact so that it gives everyone a chance to view/review it. It’s here https://builds.apache.org/view/A/view/Ant/job/Ivy-NightlyDistribution/lastSuccessfulBuild/artifact/build/. We could just push it to the site under master but I wasn’t too sure if it’s the right time to do that or if we should just cleanup the rest of the issues in the doc before starting to push it there.

>
> And just an idea: since there are a lot of pages, maybe we could organize a review at many, without useless double checks. I see 4 big parts in the doc: the ant tasks, the pages related to the ivy file, the pages related to the ivysettings, and the other pages. If 4 volunteers can do a quick review of each page, I think we can be pretty confident that we didn’t leave any ugliness somewhere. The goal wouldn’t to do a fine grain review, but ensure that everything is readable. wdyt ?
>

Sounds a good idea. I’ll start off with the “Settings” which relates to the Ivy settings file.

-Jaikiran



---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy - we have now moved to asciidoc for docs

Gintautas Grigelionis
I'd happy to help later tonight, please let me know if there's some
particular section that I should look into.
Skimming through quickly, More Examples (
http://people.apache.org/~hibou/doc/moreexamples.html) should be adjusted.

Gintas

2017-06-20 4:16 GMT+02:00 Jaikiran Pai <[hidden email]>:

> >
> > On 20-Jun-2017, at 3:38 AM, Nicolas Lalevée <[hidden email]>
> wrote:
> >
> >
> >> Le 19 juin 2017 à 04:52, Jaikiran Pai <[hidden email]> a
> écrit :
> >>
> >> The documentation for ant-ivy project has now been migrated to
> asciidoc. The migration used a tool developed by Nicolas to migrate the
> xooki backed HTML docs to asciidoc. This tool auto-generated the asciidoc
> text and for most part no other changes were needed. However, there are
> some fixes the generated asciidoc will need which I’m doing and will
> continue to do in the coming days to fix any issues with the generated doc.
> Once the fixes are done, soon, we’ll remove the xooki backed documentation
> completely from our git repo. For now though, any new documentation or
> changes should go into the asciidoc files.
> >
> > I did a general grep about finding non translated html markup, and I
> have cleaned the ones I have found.
> > I have pushed the result here: http://people.apache.org/~hibou/doc/ <
> http://people.apache.org/~hibou/doc/>
> >
> > Probably we can start pushing it to the site, since there is section
> dedicated to the trunk version of the doc (which should be probably renamed
> master).
> > http://ant.apache.org/ivy/history/trunk/index.html <
> http://ant.apache.org/ivy/history/trunk/index.html>
> > It would be an opportunity to get an idea of what would it mean when a
> release will happen.
>
> I actually forgot to send a mail yesterday, but I setup our nightly Ivy
> job on Jenkins to publish the latest generated docs as build artifact so
> that it gives everyone a chance to view/review it. It’s here
> https://builds.apache.org/view/A/view/Ant/job/Ivy-NightlyDistribution/
> lastSuccessfulBuild/artifact/build/. We could just push it to the site
> under master but I wasn’t too sure if it’s the right time to do that or if
> we should just cleanup the rest of the issues in the doc before starting to
> push it there.
>
> >
> > And just an idea: since there are a lot of pages, maybe we could
> organize a review at many, without useless double checks. I see 4 big parts
> in the doc: the ant tasks, the pages related to the ivy file, the pages
> related to the ivysettings, and the other pages. If 4 volunteers can do a
> quick review of each page, I think we can be pretty confident that we
> didn’t leave any ugliness somewhere. The goal wouldn’t to do a fine grain
> review, but ensure that everything is readable. wdyt ?
> >
>
> Sounds a good idea. I’ll start off with the “Settings” which relates to
> the Ivy settings file.
>
> -Jaikiran
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
Loading...