Re: Ivy website - fixing a Quickstart documentation live

[J Pai <ja...@gmail.com>]

I just realized that attachments aren’t delivered to the mailing list. So here’s the gist link to the patch https://gist.github.com/jaikiran/992e642410afb5683e461d1bd6e01503 which I was talking about in my mail.


-Jaikiran
On 26-May-2017, at 12:36 PM, J Pai <ja...@gmail.com> wrote:

So I got this site generation working locally (had to fix a xooki script to make it work with Nashorn. The attached patch includes the fix). 

At this point, I need help to commit the newly generated doc fixes to the SVN. I’ve attached a patch file for it and will explain what it is doing.

The changes/patch relates to _one_ of the more important issues noted in the JIRA https://issues.apache.org/jira/browse/IVY-1542. That JIRA lists more than one issue with the latest docs. However, the missing .png and .css don’t directly contribute to anything noticeable, so I haven’t included it in this patch (and probably will look into it separately). The issue that this patch fixes is the more important one:

> Code examples are missing. About 2/3 of the way down the page are two code examples that are rendering as just a black rectangle for me. The underlying html looks like it has <pre> tags with no content.


The way these tutorial docs are generated, during the build, it triggers the build of quickstart examples and dumps the logs into files. The log files are then referred to via xooki references and the contents of those log files are inlined within the div tags. So I went ahead and built these tutorials on 2.4.0 tag of Ivy project, generated those logs and then regenerated the site with these logs in the relevant folder. The generated documentation now has these output inlined correctly in the quickstart and various other docs.

The attached patch was generated with https://svn.apache.org/repos/asf/ant/site/ as the root of the SVN checkout. So whoever is applying the patch will have to cd to that directory and then apply it. Let me know if you run into issues or if any changes are necessary in this patch.

As for the other two issues noted in that JIRA, I’m planning to remove references to the non-existent .css and .png files and submit that as a separate patch.

-Jaikiran

<fix-latest-milestone-docs.patch>




On 26-May-2017, at 10:39 AM, J Pai <ja...@gmail.com> wrote:

Thanks everyone for the inputs.

I’m trying to get a proper build going locally for the site generation (and running into issues). Once I get a proper build and the fixes to the issues noted in that JIRA, I’ll send out an update. Hopefully soon.

-Jaikiran
On 25-May-2017, at 5:26 PM, Nicolas Lalevée <ni...@hibnet.org> wrote:

The entire Ant site is in svn:
https://svn.apache.org/repos/asf/ant/site

There is a Readme.txt explaining a little bit stuff, but seems outdated since the migration to git. For Ivy and IvyDE, part of the site is built from the source for the projects. It used to be managed via svn:externals. Now there are ant tasks to run to the fetch of the sources. I have found an old discussion [1] we had about it which should help you.

By the way, the Ivy documentation is managed by an hand crafted html editor, xooki, just is good but quite slow. I did some work some time ago (2 years ago, time flies!) to try to migrate to asciidoc [2]. I can even see that locally I have a commit which for some reason I didn’t pushed. If we are still interested, I can revive this.

Nicolas

[1] http://ant.1045680.n5.nabble.com/stuck-with-site-generation-issue-for-ivy-td5715758.html <http://ant.1045680.n5.nabble.com/stuck-with-site-generation-issue-for-ivy-td5715758.html>
[2] https://github.com/apache/ant-ivy/tree/xooki2asciidoc <https://github.com/apache/ant-ivy/tree/xooki2asciidoc>


> Le 25 mai 2017 à 06:12, J Pai <ja...@gmail.com> a écrit :
> 
> What would be the process of having the live docs of Ivy project updated to fix/update an issue in the documentation[1]? 
> 
> The quickstart documentation refers to certain log files that get auto-generated during the doc build process. It looks like those log files weren’t uploaded and are resulting in a blank text area showing up. I can run the doc generation target locally (on 2.4.0 tag) and have someone upload those files and see if shows up fine.
> 
> [1] https://issues.apache.org/jira/browse/IVY-1542
> 
> -Jaikiran
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
> For additional commands, e-mail: dev-help@ant.apache.org
> 





---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org