You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by Andrey Kurdumov <ka...@googlemail.com> on 2014/11/02 22:11:45 UTC
Documentation generation in pure Node.JS
Hello guys,
I almost finish implementing
https://issues.apache.org/jira/browse/CB-6751
In short this is implementation of Cordova Docs website generator using
Node.JS instead of relying on Vagrant and Ruby.
Summary of work:
- Implementation duplicates Ruby code as much as possible. Tests which was
written for Ruby, was reimplemented in JS.
- Created new executable genjs in the bin folder, which generate
documentation to the *public/test* folder, instead of *public* folder, so
differences between implementation could be found using standard diffing
tools.
- Implementation verified on Mac and Windows.
- Small improvements to CLI interface (single language generation, single
version generation, added verbose mode for tracing execution)
- As I can tell, JS implementation produce almost same HTML code as Ruby
version. I done some smoke testing of changes and seems that everything is
good, but willing that you guys look at the docs too.
To make this works with existing documentation and support Windows, I have
to fork existing implementation of joDoc-js (
https://github.com/kant2002/jodoc-js)
Issues:
- Windows suffer from occasional EPERM issues during generation of the docs.
Pull request for that implementation is here:
https://github.com/apache/cordova-docs/pull/236
Best regards,
Andrey
Re: Documentation generation in pure Node.JS
Posted by Marcel Kinard <cm...@gmail.com>.
Woohoo!
> On Thu, Dec 25, 2014 at 12:02 AM, Andrey Kurdumov <ka...@googlemail.com>
> wrote:
>
>> README.md updated and Ruby files deleted.
>> Also create script which should replace Rakefile in case if somebody need
>> it.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
Re: Documentation generation in pure Node.JS
Posted by Andrew Grieve <ag...@chromium.org>.
Merged!
On Thu, Dec 25, 2014 at 12:02 AM, Andrey Kurdumov <ka...@googlemail.com>
wrote:
> README.md updated and Ruby files deleted.
> Also create script which should replace Rakefile in case if somebody need
> it.
>
> See there: https://github.com/apache/cordova-docs/pull/249
>
> 2014-12-23 22:28 GMT+06:00 Andrew Grieve <ag...@chromium.org>:
>
> > This is now merged. Woot!
> > What I did:
> > - Looked through the code (skimmed mostly)
> > - Ran bin/genjs
> > - Ran npm test
> > - spot-checked output within public/test
> > Everything looks great to me! Only things I did:
> > - Squashed into a single commit
> > - Removed trailing whitespace
> > - Added a couple of missing semicolons to appease npm test
> >
> > Other tidbits I saw:
> > - There was one spot in jodoc.js where it was using "/"s instead of
> > path.join(), so may not work on windows
> > - jodoc is being run via shelljs.exec(), which is known to slow things
> down
> > quite a bit. Would be good to switch this to child_process.exec(), or
> maybe
> > just require() it and call it's main()?
> >
> > Next steps? From what I can see:
> > - update the README.md to describe how to generate using the new
> generator
> > - delete the ruby files!
> >
> > Clearly a LOT of work and care went into this change. Great job!
> >
> >
> > On Thu, Dec 18, 2014 at 3:29 AM, Andrey Kurdumov <
> kant2002@googlemail.com>
> > wrote:
> > >
> > > Does anybody except Michael look on the documentation generation?
> > > I need this as a basis for future work on tools which helps me increase
> > > quality of translation.
> > > For first I want to have tool which ensures that autolinking in
> > translated
> > > docs is working in same places as in original English translation.
> > >
> > > 2014-12-11 23:17 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
> > > >
> > > > Andrey, you're approach sounds incredibly thorough! I'll set aside
> some
> > > > time to test your pull request and see how it runs on my system.
> Today
> > is
> > > > already full, so I'll try to have some time set aside for tomorrow or
> > the
> > > > weekend.
> > > >
> > > > If anyone else is available to test it, that would be great as well!
> > > >
> > > > https://github.com/apache/cordova-docs/pull/236
> > > >
> > > > Michael
> > > >
> > > > On Wed, Dec 10, 2014 at 7:37 PM, Andrey Kurdumov <
> > > kant2002@googlemail.com>
> > > > wrote:
> > > >
> > > > > Thanks,
> > > > > 1. Already play with marked options and don't find any way to
> resolve
> > > > that
> > > > > using that path. Now I done following:
> > > > > a) Generate latest docs using Ruby & JS
> > > > > b) Made changes to the original MD files, so previously
> generated
> > > > > version with Ruby will match with generated using JS
> > > > > c) Regenerate Ruby version against changed MD files and verify
> > that
> > > > > docs still the same as it was originally.
> > > > > I made changes to MD files so all languages produce identical
> results
> > > > > Original MD + Ruby <==> Modified MD + JS <==> Modified MD + Ruby
> > > > > Most of the changes is inserting or removing blank lines, and most
> of
> > > > > changes is duplication of same place in the MD file, which was
> caused
> > > by
> > > > > copying file to new version.
> > > > >
> > > > > NOTE for documentation writers, Section header should be separated
> by
> > > two
> > > > > lines most of the time for documentation to be correctly generated.
> > > > >
> > > > > 2. Then prefer to drop generation for that _index.json.
> > > > >
> > > > > I'm fully ready for this pull request to be merged, I don't see now
> > any
> > > > > piece of docs that different from original.
> > > > >
> > > > > 2014-12-08 23:22 GMT+06:00 Michael Brooks <
> michael@michaelbrooks.ca
> > >:
> > > > >
> > > > > > Hi Andrey,
> > > > > >
> > > > > > 1. marked is certainly the most popular and active markdown
> > generate
> > > > for
> > > > > > node. You may want to consider playing around with the options it
> > > > offers.
> > > > > >
> > > > > > 2. _index.json was produced by the original joDoc generator, so
> the
> > > > > > node-version may not support it. To the best of my knowledge, no
> > one
> > > > uses
> > > > > > the JSON interface, which was intended to act as a simple API to
> > the
> > > > > > documentation.
> > > > > >
> > > > > > Nice work!
> > > > > > Michael
> > > > > >
> > > > > > On Sat, Dec 6, 2014 at 11:00 AM, Andrey Kurdumov <
> > > > > kant2002@googlemail.com>
> > > > > > wrote:
> > > > > >
> > > > > > > Hi all,
> > > > > > >
> > > > > > > Bumping this thread again, since looks like I almost finish
> port
> > > Ruby
> > > > > > > version of documents generation to JS.
> > > > > > > I fix issues which you discover last time, and create
> validation
> > > > script
> > > > > > > which theoretically could spot differences between old version
> > and
> > > > new
> > > > > > one.
> > > > > > > So far everything looks good except following 2 items:
> > > > > > >
> > > > > > > 1. JS version of Markdown parser currently in use is more
> strict
> > > then
> > > > > > Ruby
> > > > > > > version (Used NPM module *marked*). This results that some
> small
> > > > subset
> > > > > > of
> > > > > > > files produce not identical output in those places where nested
> > > lists
> > > > > are
> > > > > > > used. This could be fixed by adding or removing empty lines.
> I'm
> > > not
> > > > > sure
> > > > > > > should I change original MD files, or search for better
> Markdown
> > > > > parser.
> > > > > > If
> > > > > > > somebody know better MD parser I would appreciate pointing on
> it.
> > > > > > > 2. In original docs some unknown _index.json file. Does anybody
> > > know
> > > > > who
> > > > > > is
> > > > > > > producing this file and how it is generated, so I could
> duplicate
> > > it
> > > > > > > generation too.
> > > > > > >
> > > > > > > I sure that this is what only thing which prevent me from
> > thinking
> > > > that
> > > > > > > everything is done.
> > > > > > >
> > > > > > > Best regards,
> > > > > > > Andrey
> > > > > > >
> > > > > > >
> > > > > > > 2014-11-04 23:33 GMT+06:00 Michael Brooks <
> > > michael@michaelbrooks.ca
> > > > >:
> > > > > > >
> > > > > > > > Hi Audrey,
> > > > > > > >
> > > > > > > > Thanks for tackling this issue!
> > > > > > > >
> > > > > > > > Truth be told, we want to move away from jsdoc entirely.
> Years
> > > ago,
> > > > > we
> > > > > > > > thought that the auto-linking and other auto-magical aspects
> of
> > > > jsdoc
> > > > > > > would
> > > > > > > > be nice, but it's caused more problems than good. The ruby
> > > > > environment
> > > > > > is
> > > > > > > > also troublesome, although we've largely solved that with a
> > > Vagrant
> > > > > > > image.
> > > > > > > >
> > > > > > > > However, it sounds as though you've managed to re-implement
> all
> > > of
> > > > > the
> > > > > > > > original middleware that we created. If you're confident that
> > the
> > > > > docs
> > > > > > > will
> > > > > > > > generate the same as before, then I think we'd happily
> welcome
> > a
> > > > > > > pure-node
> > > > > > > > documentation generator. I think we will be moving to a
> > different
> > > > doc
> > > > > > > > generation approach in the future, but your re-implementation
> > > will
> > > > > be a
> > > > > > > > great transitional step!
> > > > > > > >
> > > > > > > > I'd be happy to review your pull request once you've squashed
> > the
> > > > > > various
> > > > > > > > bugs.
> > > > > > > >
> > > > > > > > Cheers,
> > > > > > > > Michael
> > > > > > > >
> > > > > > > > On Tue, Nov 4, 2014 at 3:54 AM, Andrey Kurdumov <
> > > > > > kant2002@googlemail.com
> > > > > > > >
> > > > > > > > wrote:
> > > > > > > >
> > > > > > > > > I also find that links in Guides is missing. Not yet sure
> why
> > > is
> > > > > that
> > > > > > > > > looking into that.
> > > > > > > > > Issue which Shazron discover should be fixed now.
> > > > > > > > >
> > > > > > > > > 2014-11-04 3:00 GMT+06:00 Michal Mocny <
> mmocny@chromium.org
> > >:
> > > > > > > > >
> > > > > > > > > > Just tried it using the steps Shaz listed on the PR and
> its
> > > > > working
> > > > > > > for
> > > > > > > > > me
> > > > > > > > > > fine. However, there are some warnings during generation
> > > > (bunch
> > > > > of
> > > > > > > > "Did
> > > > > > > > > > not found link for the keyword"), and the generated pages
> > > > appear
> > > > > to
> > > > > > > > have
> > > > > > > > > > some links missing (such as the first page, Guides do not
> > > link
> > > > to
> > > > > > > > > > anything). Unsure if the warning is the cause of the
> > missing
> > > > > > links.
> > > > > > > > > >
> > > > > > > > > > Keep chugging away!
> > > > > > > > > >
> > > > > > > > > > -Michal
> > > > > > > > > >
> > > > > > > > > > On Mon, Nov 3, 2014 at 2:39 PM, Andrew Grieve <
> > > > > > agrieve@chromium.org>
> > > > > > > > > > wrote:
> > > > > > > > > >
> > > > > > > > > > > Love that you're working on this!
> > > > > > > > > > >
> > > > > > > > > > > On Mon, Nov 3, 2014 at 12:57 AM, Shazron <
> > > shazron@gmail.com>
> > > > > > > wrote:
> > > > > > > > > > >
> > > > > > > > > > > > Thanks Andrey,
> > > > > > > > > > > > I tested it out but I ran into problems. See my
> comment
> > > on
> > > > > your
> > > > > > > > pull
> > > > > > > > > > > > request.
> > > > > > > > > > > >
> > > > > > > > > > > > On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <
> > > > > > > > > > kant2002@googlemail.com
> > > > > > > > > > > >
> > > > > > > > > > > > wrote:
> > > > > > > > > > > >
> > > > > > > > > > > > > Hello guys,
> > > > > > > > > > > > >
> > > > > > > > > > > > > I almost finish implementing
> > > > > > > > > > > > > https://issues.apache.org/jira/browse/CB-6751
> > > > > > > > > > > > >
> > > > > > > > > > > > > In short this is implementation of Cordova Docs
> > website
> > > > > > > generator
> > > > > > > > > > using
> > > > > > > > > > > > > Node.JS instead of relying on Vagrant and Ruby.
> > > > > > > > > > > > >
> > > > > > > > > > > > > Summary of work:
> > > > > > > > > > > > > - Implementation duplicates Ruby code as much as
> > > > possible.
> > > > > > > Tests
> > > > > > > > > > which
> > > > > > > > > > > > was
> > > > > > > > > > > > > written for Ruby, was reimplemented in JS.
> > > > > > > > > > > > > - Created new executable genjs in the bin folder,
> > which
> > > > > > > generate
> > > > > > > > > > > > > documentation to the *public/test* folder, instead
> of
> > > > > > *public*
> > > > > > > > > > folder,
> > > > > > > > > > > so
> > > > > > > > > > > > > differences between implementation could be found
> > using
> > > > > > > standard
> > > > > > > > > > > diffing
> > > > > > > > > > > > > tools.
> > > > > > > > > > > > > - Implementation verified on Mac and Windows.
> > > > > > > > > > > > > - Small improvements to CLI interface (single
> > language
> > > > > > > > generation,
> > > > > > > > > > > single
> > > > > > > > > > > > > version generation, added verbose mode for tracing
> > > > > execution)
> > > > > > > > > > > > > - As I can tell, JS implementation produce almost
> > same
> > > > HTML
> > > > > > > code
> > > > > > > > as
> > > > > > > > > > > Ruby
> > > > > > > > > > > > > version. I done some smoke testing of changes and
> > seems
> > > > > that
> > > > > > > > > > everything
> > > > > > > > > > > > is
> > > > > > > > > > > > > good, but willing that you guys look at the docs
> too.
> > > > > > > > > > > > >
> > > > > > > > > > > > > To make this works with existing documentation and
> > > > support
> > > > > > > > > Windows, I
> > > > > > > > > > > > have
> > > > > > > > > > > > > to fork existing implementation of joDoc-js (
> > > > > > > > > > > > > https://github.com/kant2002/jodoc-js)
> > > > > > > > > > > > >
> > > > > > > > > > > > > Issues:
> > > > > > > > > > > > > - Windows suffer from occasional EPERM issues
> during
> > > > > > generation
> > > > > > > > of
> > > > > > > > > > the
> > > > > > > > > > > > > docs.
> > > > > > > > > > > > >
> > > > > > > > > > > > > Pull request for that implementation is here:
> > > > > > > > > > > > > https://github.com/apache/cordova-docs/pull/236
> > > > > > > > > > > > >
> > > > > > > > > > > > > Best regards,
> > > > > > > > > > > > > Andrey
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: Documentation generation in pure Node.JS
Posted by Andrey Kurdumov <ka...@googlemail.com>.
README.md updated and Ruby files deleted.
Also create script which should replace Rakefile in case if somebody need
it.
See there: https://github.com/apache/cordova-docs/pull/249
2014-12-23 22:28 GMT+06:00 Andrew Grieve <ag...@chromium.org>:
> This is now merged. Woot!
> What I did:
> - Looked through the code (skimmed mostly)
> - Ran bin/genjs
> - Ran npm test
> - spot-checked output within public/test
> Everything looks great to me! Only things I did:
> - Squashed into a single commit
> - Removed trailing whitespace
> - Added a couple of missing semicolons to appease npm test
>
> Other tidbits I saw:
> - There was one spot in jodoc.js where it was using "/"s instead of
> path.join(), so may not work on windows
> - jodoc is being run via shelljs.exec(), which is known to slow things down
> quite a bit. Would be good to switch this to child_process.exec(), or maybe
> just require() it and call it's main()?
>
> Next steps? From what I can see:
> - update the README.md to describe how to generate using the new generator
> - delete the ruby files!
>
> Clearly a LOT of work and care went into this change. Great job!
>
>
> On Thu, Dec 18, 2014 at 3:29 AM, Andrey Kurdumov <ka...@googlemail.com>
> wrote:
> >
> > Does anybody except Michael look on the documentation generation?
> > I need this as a basis for future work on tools which helps me increase
> > quality of translation.
> > For first I want to have tool which ensures that autolinking in
> translated
> > docs is working in same places as in original English translation.
> >
> > 2014-12-11 23:17 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
> > >
> > > Andrey, you're approach sounds incredibly thorough! I'll set aside some
> > > time to test your pull request and see how it runs on my system. Today
> is
> > > already full, so I'll try to have some time set aside for tomorrow or
> the
> > > weekend.
> > >
> > > If anyone else is available to test it, that would be great as well!
> > >
> > > https://github.com/apache/cordova-docs/pull/236
> > >
> > > Michael
> > >
> > > On Wed, Dec 10, 2014 at 7:37 PM, Andrey Kurdumov <
> > kant2002@googlemail.com>
> > > wrote:
> > >
> > > > Thanks,
> > > > 1. Already play with marked options and don't find any way to resolve
> > > that
> > > > using that path. Now I done following:
> > > > a) Generate latest docs using Ruby & JS
> > > > b) Made changes to the original MD files, so previously generated
> > > > version with Ruby will match with generated using JS
> > > > c) Regenerate Ruby version against changed MD files and verify
> that
> > > > docs still the same as it was originally.
> > > > I made changes to MD files so all languages produce identical results
> > > > Original MD + Ruby <==> Modified MD + JS <==> Modified MD + Ruby
> > > > Most of the changes is inserting or removing blank lines, and most of
> > > > changes is duplication of same place in the MD file, which was caused
> > by
> > > > copying file to new version.
> > > >
> > > > NOTE for documentation writers, Section header should be separated by
> > two
> > > > lines most of the time for documentation to be correctly generated.
> > > >
> > > > 2. Then prefer to drop generation for that _index.json.
> > > >
> > > > I'm fully ready for this pull request to be merged, I don't see now
> any
> > > > piece of docs that different from original.
> > > >
> > > > 2014-12-08 23:22 GMT+06:00 Michael Brooks <michael@michaelbrooks.ca
> >:
> > > >
> > > > > Hi Andrey,
> > > > >
> > > > > 1. marked is certainly the most popular and active markdown
> generate
> > > for
> > > > > node. You may want to consider playing around with the options it
> > > offers.
> > > > >
> > > > > 2. _index.json was produced by the original joDoc generator, so the
> > > > > node-version may not support it. To the best of my knowledge, no
> one
> > > uses
> > > > > the JSON interface, which was intended to act as a simple API to
> the
> > > > > documentation.
> > > > >
> > > > > Nice work!
> > > > > Michael
> > > > >
> > > > > On Sat, Dec 6, 2014 at 11:00 AM, Andrey Kurdumov <
> > > > kant2002@googlemail.com>
> > > > > wrote:
> > > > >
> > > > > > Hi all,
> > > > > >
> > > > > > Bumping this thread again, since looks like I almost finish port
> > Ruby
> > > > > > version of documents generation to JS.
> > > > > > I fix issues which you discover last time, and create validation
> > > script
> > > > > > which theoretically could spot differences between old version
> and
> > > new
> > > > > one.
> > > > > > So far everything looks good except following 2 items:
> > > > > >
> > > > > > 1. JS version of Markdown parser currently in use is more strict
> > then
> > > > > Ruby
> > > > > > version (Used NPM module *marked*). This results that some small
> > > subset
> > > > > of
> > > > > > files produce not identical output in those places where nested
> > lists
> > > > are
> > > > > > used. This could be fixed by adding or removing empty lines. I'm
> > not
> > > > sure
> > > > > > should I change original MD files, or search for better Markdown
> > > > parser.
> > > > > If
> > > > > > somebody know better MD parser I would appreciate pointing on it.
> > > > > > 2. In original docs some unknown _index.json file. Does anybody
> > know
> > > > who
> > > > > is
> > > > > > producing this file and how it is generated, so I could duplicate
> > it
> > > > > > generation too.
> > > > > >
> > > > > > I sure that this is what only thing which prevent me from
> thinking
> > > that
> > > > > > everything is done.
> > > > > >
> > > > > > Best regards,
> > > > > > Andrey
> > > > > >
> > > > > >
> > > > > > 2014-11-04 23:33 GMT+06:00 Michael Brooks <
> > michael@michaelbrooks.ca
> > > >:
> > > > > >
> > > > > > > Hi Audrey,
> > > > > > >
> > > > > > > Thanks for tackling this issue!
> > > > > > >
> > > > > > > Truth be told, we want to move away from jsdoc entirely. Years
> > ago,
> > > > we
> > > > > > > thought that the auto-linking and other auto-magical aspects of
> > > jsdoc
> > > > > > would
> > > > > > > be nice, but it's caused more problems than good. The ruby
> > > > environment
> > > > > is
> > > > > > > also troublesome, although we've largely solved that with a
> > Vagrant
> > > > > > image.
> > > > > > >
> > > > > > > However, it sounds as though you've managed to re-implement all
> > of
> > > > the
> > > > > > > original middleware that we created. If you're confident that
> the
> > > > docs
> > > > > > will
> > > > > > > generate the same as before, then I think we'd happily welcome
> a
> > > > > > pure-node
> > > > > > > documentation generator. I think we will be moving to a
> different
> > > doc
> > > > > > > generation approach in the future, but your re-implementation
> > will
> > > > be a
> > > > > > > great transitional step!
> > > > > > >
> > > > > > > I'd be happy to review your pull request once you've squashed
> the
> > > > > various
> > > > > > > bugs.
> > > > > > >
> > > > > > > Cheers,
> > > > > > > Michael
> > > > > > >
> > > > > > > On Tue, Nov 4, 2014 at 3:54 AM, Andrey Kurdumov <
> > > > > kant2002@googlemail.com
> > > > > > >
> > > > > > > wrote:
> > > > > > >
> > > > > > > > I also find that links in Guides is missing. Not yet sure why
> > is
> > > > that
> > > > > > > > looking into that.
> > > > > > > > Issue which Shazron discover should be fixed now.
> > > > > > > >
> > > > > > > > 2014-11-04 3:00 GMT+06:00 Michal Mocny <mmocny@chromium.org
> >:
> > > > > > > >
> > > > > > > > > Just tried it using the steps Shaz listed on the PR and its
> > > > working
> > > > > > for
> > > > > > > > me
> > > > > > > > > fine. However, there are some warnings during generation
> > > (bunch
> > > > of
> > > > > > > "Did
> > > > > > > > > not found link for the keyword"), and the generated pages
> > > appear
> > > > to
> > > > > > > have
> > > > > > > > > some links missing (such as the first page, Guides do not
> > link
> > > to
> > > > > > > > > anything). Unsure if the warning is the cause of the
> missing
> > > > > links.
> > > > > > > > >
> > > > > > > > > Keep chugging away!
> > > > > > > > >
> > > > > > > > > -Michal
> > > > > > > > >
> > > > > > > > > On Mon, Nov 3, 2014 at 2:39 PM, Andrew Grieve <
> > > > > agrieve@chromium.org>
> > > > > > > > > wrote:
> > > > > > > > >
> > > > > > > > > > Love that you're working on this!
> > > > > > > > > >
> > > > > > > > > > On Mon, Nov 3, 2014 at 12:57 AM, Shazron <
> > shazron@gmail.com>
> > > > > > wrote:
> > > > > > > > > >
> > > > > > > > > > > Thanks Andrey,
> > > > > > > > > > > I tested it out but I ran into problems. See my comment
> > on
> > > > your
> > > > > > > pull
> > > > > > > > > > > request.
> > > > > > > > > > >
> > > > > > > > > > > On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <
> > > > > > > > > kant2002@googlemail.com
> > > > > > > > > > >
> > > > > > > > > > > wrote:
> > > > > > > > > > >
> > > > > > > > > > > > Hello guys,
> > > > > > > > > > > >
> > > > > > > > > > > > I almost finish implementing
> > > > > > > > > > > > https://issues.apache.org/jira/browse/CB-6751
> > > > > > > > > > > >
> > > > > > > > > > > > In short this is implementation of Cordova Docs
> website
> > > > > > generator
> > > > > > > > > using
> > > > > > > > > > > > Node.JS instead of relying on Vagrant and Ruby.
> > > > > > > > > > > >
> > > > > > > > > > > > Summary of work:
> > > > > > > > > > > > - Implementation duplicates Ruby code as much as
> > > possible.
> > > > > > Tests
> > > > > > > > > which
> > > > > > > > > > > was
> > > > > > > > > > > > written for Ruby, was reimplemented in JS.
> > > > > > > > > > > > - Created new executable genjs in the bin folder,
> which
> > > > > > generate
> > > > > > > > > > > > documentation to the *public/test* folder, instead of
> > > > > *public*
> > > > > > > > > folder,
> > > > > > > > > > so
> > > > > > > > > > > > differences between implementation could be found
> using
> > > > > > standard
> > > > > > > > > > diffing
> > > > > > > > > > > > tools.
> > > > > > > > > > > > - Implementation verified on Mac and Windows.
> > > > > > > > > > > > - Small improvements to CLI interface (single
> language
> > > > > > > generation,
> > > > > > > > > > single
> > > > > > > > > > > > version generation, added verbose mode for tracing
> > > > execution)
> > > > > > > > > > > > - As I can tell, JS implementation produce almost
> same
> > > HTML
> > > > > > code
> > > > > > > as
> > > > > > > > > > Ruby
> > > > > > > > > > > > version. I done some smoke testing of changes and
> seems
> > > > that
> > > > > > > > > everything
> > > > > > > > > > > is
> > > > > > > > > > > > good, but willing that you guys look at the docs too.
> > > > > > > > > > > >
> > > > > > > > > > > > To make this works with existing documentation and
> > > support
> > > > > > > > Windows, I
> > > > > > > > > > > have
> > > > > > > > > > > > to fork existing implementation of joDoc-js (
> > > > > > > > > > > > https://github.com/kant2002/jodoc-js)
> > > > > > > > > > > >
> > > > > > > > > > > > Issues:
> > > > > > > > > > > > - Windows suffer from occasional EPERM issues during
> > > > > generation
> > > > > > > of
> > > > > > > > > the
> > > > > > > > > > > > docs.
> > > > > > > > > > > >
> > > > > > > > > > > > Pull request for that implementation is here:
> > > > > > > > > > > > https://github.com/apache/cordova-docs/pull/236
> > > > > > > > > > > >
> > > > > > > > > > > > Best regards,
> > > > > > > > > > > > Andrey
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: Documentation generation in pure Node.JS
Posted by Andrew Grieve <ag...@chromium.org>.
This is now merged. Woot!
What I did:
- Looked through the code (skimmed mostly)
- Ran bin/genjs
- Ran npm test
- spot-checked output within public/test
Everything looks great to me! Only things I did:
- Squashed into a single commit
- Removed trailing whitespace
- Added a couple of missing semicolons to appease npm test
Other tidbits I saw:
- There was one spot in jodoc.js where it was using "/"s instead of
path.join(), so may not work on windows
- jodoc is being run via shelljs.exec(), which is known to slow things down
quite a bit. Would be good to switch this to child_process.exec(), or maybe
just require() it and call it's main()?
Next steps? From what I can see:
- update the README.md to describe how to generate using the new generator
- delete the ruby files!
Clearly a LOT of work and care went into this change. Great job!
On Thu, Dec 18, 2014 at 3:29 AM, Andrey Kurdumov <ka...@googlemail.com>
wrote:
>
> Does anybody except Michael look on the documentation generation?
> I need this as a basis for future work on tools which helps me increase
> quality of translation.
> For first I want to have tool which ensures that autolinking in translated
> docs is working in same places as in original English translation.
>
> 2014-12-11 23:17 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
> >
> > Andrey, you're approach sounds incredibly thorough! I'll set aside some
> > time to test your pull request and see how it runs on my system. Today is
> > already full, so I'll try to have some time set aside for tomorrow or the
> > weekend.
> >
> > If anyone else is available to test it, that would be great as well!
> >
> > https://github.com/apache/cordova-docs/pull/236
> >
> > Michael
> >
> > On Wed, Dec 10, 2014 at 7:37 PM, Andrey Kurdumov <
> kant2002@googlemail.com>
> > wrote:
> >
> > > Thanks,
> > > 1. Already play with marked options and don't find any way to resolve
> > that
> > > using that path. Now I done following:
> > > a) Generate latest docs using Ruby & JS
> > > b) Made changes to the original MD files, so previously generated
> > > version with Ruby will match with generated using JS
> > > c) Regenerate Ruby version against changed MD files and verify that
> > > docs still the same as it was originally.
> > > I made changes to MD files so all languages produce identical results
> > > Original MD + Ruby <==> Modified MD + JS <==> Modified MD + Ruby
> > > Most of the changes is inserting or removing blank lines, and most of
> > > changes is duplication of same place in the MD file, which was caused
> by
> > > copying file to new version.
> > >
> > > NOTE for documentation writers, Section header should be separated by
> two
> > > lines most of the time for documentation to be correctly generated.
> > >
> > > 2. Then prefer to drop generation for that _index.json.
> > >
> > > I'm fully ready for this pull request to be merged, I don't see now any
> > > piece of docs that different from original.
> > >
> > > 2014-12-08 23:22 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
> > >
> > > > Hi Andrey,
> > > >
> > > > 1. marked is certainly the most popular and active markdown generate
> > for
> > > > node. You may want to consider playing around with the options it
> > offers.
> > > >
> > > > 2. _index.json was produced by the original joDoc generator, so the
> > > > node-version may not support it. To the best of my knowledge, no one
> > uses
> > > > the JSON interface, which was intended to act as a simple API to the
> > > > documentation.
> > > >
> > > > Nice work!
> > > > Michael
> > > >
> > > > On Sat, Dec 6, 2014 at 11:00 AM, Andrey Kurdumov <
> > > kant2002@googlemail.com>
> > > > wrote:
> > > >
> > > > > Hi all,
> > > > >
> > > > > Bumping this thread again, since looks like I almost finish port
> Ruby
> > > > > version of documents generation to JS.
> > > > > I fix issues which you discover last time, and create validation
> > script
> > > > > which theoretically could spot differences between old version and
> > new
> > > > one.
> > > > > So far everything looks good except following 2 items:
> > > > >
> > > > > 1. JS version of Markdown parser currently in use is more strict
> then
> > > > Ruby
> > > > > version (Used NPM module *marked*). This results that some small
> > subset
> > > > of
> > > > > files produce not identical output in those places where nested
> lists
> > > are
> > > > > used. This could be fixed by adding or removing empty lines. I'm
> not
> > > sure
> > > > > should I change original MD files, or search for better Markdown
> > > parser.
> > > > If
> > > > > somebody know better MD parser I would appreciate pointing on it.
> > > > > 2. In original docs some unknown _index.json file. Does anybody
> know
> > > who
> > > > is
> > > > > producing this file and how it is generated, so I could duplicate
> it
> > > > > generation too.
> > > > >
> > > > > I sure that this is what only thing which prevent me from thinking
> > that
> > > > > everything is done.
> > > > >
> > > > > Best regards,
> > > > > Andrey
> > > > >
> > > > >
> > > > > 2014-11-04 23:33 GMT+06:00 Michael Brooks <
> michael@michaelbrooks.ca
> > >:
> > > > >
> > > > > > Hi Audrey,
> > > > > >
> > > > > > Thanks for tackling this issue!
> > > > > >
> > > > > > Truth be told, we want to move away from jsdoc entirely. Years
> ago,
> > > we
> > > > > > thought that the auto-linking and other auto-magical aspects of
> > jsdoc
> > > > > would
> > > > > > be nice, but it's caused more problems than good. The ruby
> > > environment
> > > > is
> > > > > > also troublesome, although we've largely solved that with a
> Vagrant
> > > > > image.
> > > > > >
> > > > > > However, it sounds as though you've managed to re-implement all
> of
> > > the
> > > > > > original middleware that we created. If you're confident that the
> > > docs
> > > > > will
> > > > > > generate the same as before, then I think we'd happily welcome a
> > > > > pure-node
> > > > > > documentation generator. I think we will be moving to a different
> > doc
> > > > > > generation approach in the future, but your re-implementation
> will
> > > be a
> > > > > > great transitional step!
> > > > > >
> > > > > > I'd be happy to review your pull request once you've squashed the
> > > > various
> > > > > > bugs.
> > > > > >
> > > > > > Cheers,
> > > > > > Michael
> > > > > >
> > > > > > On Tue, Nov 4, 2014 at 3:54 AM, Andrey Kurdumov <
> > > > kant2002@googlemail.com
> > > > > >
> > > > > > wrote:
> > > > > >
> > > > > > > I also find that links in Guides is missing. Not yet sure why
> is
> > > that
> > > > > > > looking into that.
> > > > > > > Issue which Shazron discover should be fixed now.
> > > > > > >
> > > > > > > 2014-11-04 3:00 GMT+06:00 Michal Mocny <mm...@chromium.org>:
> > > > > > >
> > > > > > > > Just tried it using the steps Shaz listed on the PR and its
> > > working
> > > > > for
> > > > > > > me
> > > > > > > > fine. However, there are some warnings during generation
> > (bunch
> > > of
> > > > > > "Did
> > > > > > > > not found link for the keyword"), and the generated pages
> > appear
> > > to
> > > > > > have
> > > > > > > > some links missing (such as the first page, Guides do not
> link
> > to
> > > > > > > > anything). Unsure if the warning is the cause of the missing
> > > > links.
> > > > > > > >
> > > > > > > > Keep chugging away!
> > > > > > > >
> > > > > > > > -Michal
> > > > > > > >
> > > > > > > > On Mon, Nov 3, 2014 at 2:39 PM, Andrew Grieve <
> > > > agrieve@chromium.org>
> > > > > > > > wrote:
> > > > > > > >
> > > > > > > > > Love that you're working on this!
> > > > > > > > >
> > > > > > > > > On Mon, Nov 3, 2014 at 12:57 AM, Shazron <
> shazron@gmail.com>
> > > > > wrote:
> > > > > > > > >
> > > > > > > > > > Thanks Andrey,
> > > > > > > > > > I tested it out but I ran into problems. See my comment
> on
> > > your
> > > > > > pull
> > > > > > > > > > request.
> > > > > > > > > >
> > > > > > > > > > On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <
> > > > > > > > kant2002@googlemail.com
> > > > > > > > > >
> > > > > > > > > > wrote:
> > > > > > > > > >
> > > > > > > > > > > Hello guys,
> > > > > > > > > > >
> > > > > > > > > > > I almost finish implementing
> > > > > > > > > > > https://issues.apache.org/jira/browse/CB-6751
> > > > > > > > > > >
> > > > > > > > > > > In short this is implementation of Cordova Docs website
> > > > > generator
> > > > > > > > using
> > > > > > > > > > > Node.JS instead of relying on Vagrant and Ruby.
> > > > > > > > > > >
> > > > > > > > > > > Summary of work:
> > > > > > > > > > > - Implementation duplicates Ruby code as much as
> > possible.
> > > > > Tests
> > > > > > > > which
> > > > > > > > > > was
> > > > > > > > > > > written for Ruby, was reimplemented in JS.
> > > > > > > > > > > - Created new executable genjs in the bin folder, which
> > > > > generate
> > > > > > > > > > > documentation to the *public/test* folder, instead of
> > > > *public*
> > > > > > > > folder,
> > > > > > > > > so
> > > > > > > > > > > differences between implementation could be found using
> > > > > standard
> > > > > > > > > diffing
> > > > > > > > > > > tools.
> > > > > > > > > > > - Implementation verified on Mac and Windows.
> > > > > > > > > > > - Small improvements to CLI interface (single language
> > > > > > generation,
> > > > > > > > > single
> > > > > > > > > > > version generation, added verbose mode for tracing
> > > execution)
> > > > > > > > > > > - As I can tell, JS implementation produce almost same
> > HTML
> > > > > code
> > > > > > as
> > > > > > > > > Ruby
> > > > > > > > > > > version. I done some smoke testing of changes and seems
> > > that
> > > > > > > > everything
> > > > > > > > > > is
> > > > > > > > > > > good, but willing that you guys look at the docs too.
> > > > > > > > > > >
> > > > > > > > > > > To make this works with existing documentation and
> > support
> > > > > > > Windows, I
> > > > > > > > > > have
> > > > > > > > > > > to fork existing implementation of joDoc-js (
> > > > > > > > > > > https://github.com/kant2002/jodoc-js)
> > > > > > > > > > >
> > > > > > > > > > > Issues:
> > > > > > > > > > > - Windows suffer from occasional EPERM issues during
> > > > generation
> > > > > > of
> > > > > > > > the
> > > > > > > > > > > docs.
> > > > > > > > > > >
> > > > > > > > > > > Pull request for that implementation is here:
> > > > > > > > > > > https://github.com/apache/cordova-docs/pull/236
> > > > > > > > > > >
> > > > > > > > > > > Best regards,
> > > > > > > > > > > Andrey
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: Documentation generation in pure Node.JS
Posted by Andrey Kurdumov <ka...@googlemail.com>.
Does anybody except Michael look on the documentation generation?
I need this as a basis for future work on tools which helps me increase
quality of translation.
For first I want to have tool which ensures that autolinking in translated
docs is working in same places as in original English translation.
2014-12-11 23:17 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
>
> Andrey, you're approach sounds incredibly thorough! I'll set aside some
> time to test your pull request and see how it runs on my system. Today is
> already full, so I'll try to have some time set aside for tomorrow or the
> weekend.
>
> If anyone else is available to test it, that would be great as well!
>
> https://github.com/apache/cordova-docs/pull/236
>
> Michael
>
> On Wed, Dec 10, 2014 at 7:37 PM, Andrey Kurdumov <ka...@googlemail.com>
> wrote:
>
> > Thanks,
> > 1. Already play with marked options and don't find any way to resolve
> that
> > using that path. Now I done following:
> > a) Generate latest docs using Ruby & JS
> > b) Made changes to the original MD files, so previously generated
> > version with Ruby will match with generated using JS
> > c) Regenerate Ruby version against changed MD files and verify that
> > docs still the same as it was originally.
> > I made changes to MD files so all languages produce identical results
> > Original MD + Ruby <==> Modified MD + JS <==> Modified MD + Ruby
> > Most of the changes is inserting or removing blank lines, and most of
> > changes is duplication of same place in the MD file, which was caused by
> > copying file to new version.
> >
> > NOTE for documentation writers, Section header should be separated by two
> > lines most of the time for documentation to be correctly generated.
> >
> > 2. Then prefer to drop generation for that _index.json.
> >
> > I'm fully ready for this pull request to be merged, I don't see now any
> > piece of docs that different from original.
> >
> > 2014-12-08 23:22 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
> >
> > > Hi Andrey,
> > >
> > > 1. marked is certainly the most popular and active markdown generate
> for
> > > node. You may want to consider playing around with the options it
> offers.
> > >
> > > 2. _index.json was produced by the original joDoc generator, so the
> > > node-version may not support it. To the best of my knowledge, no one
> uses
> > > the JSON interface, which was intended to act as a simple API to the
> > > documentation.
> > >
> > > Nice work!
> > > Michael
> > >
> > > On Sat, Dec 6, 2014 at 11:00 AM, Andrey Kurdumov <
> > kant2002@googlemail.com>
> > > wrote:
> > >
> > > > Hi all,
> > > >
> > > > Bumping this thread again, since looks like I almost finish port Ruby
> > > > version of documents generation to JS.
> > > > I fix issues which you discover last time, and create validation
> script
> > > > which theoretically could spot differences between old version and
> new
> > > one.
> > > > So far everything looks good except following 2 items:
> > > >
> > > > 1. JS version of Markdown parser currently in use is more strict then
> > > Ruby
> > > > version (Used NPM module *marked*). This results that some small
> subset
> > > of
> > > > files produce not identical output in those places where nested lists
> > are
> > > > used. This could be fixed by adding or removing empty lines. I'm not
> > sure
> > > > should I change original MD files, or search for better Markdown
> > parser.
> > > If
> > > > somebody know better MD parser I would appreciate pointing on it.
> > > > 2. In original docs some unknown _index.json file. Does anybody know
> > who
> > > is
> > > > producing this file and how it is generated, so I could duplicate it
> > > > generation too.
> > > >
> > > > I sure that this is what only thing which prevent me from thinking
> that
> > > > everything is done.
> > > >
> > > > Best regards,
> > > > Andrey
> > > >
> > > >
> > > > 2014-11-04 23:33 GMT+06:00 Michael Brooks <michael@michaelbrooks.ca
> >:
> > > >
> > > > > Hi Audrey,
> > > > >
> > > > > Thanks for tackling this issue!
> > > > >
> > > > > Truth be told, we want to move away from jsdoc entirely. Years ago,
> > we
> > > > > thought that the auto-linking and other auto-magical aspects of
> jsdoc
> > > > would
> > > > > be nice, but it's caused more problems than good. The ruby
> > environment
> > > is
> > > > > also troublesome, although we've largely solved that with a Vagrant
> > > > image.
> > > > >
> > > > > However, it sounds as though you've managed to re-implement all of
> > the
> > > > > original middleware that we created. If you're confident that the
> > docs
> > > > will
> > > > > generate the same as before, then I think we'd happily welcome a
> > > > pure-node
> > > > > documentation generator. I think we will be moving to a different
> doc
> > > > > generation approach in the future, but your re-implementation will
> > be a
> > > > > great transitional step!
> > > > >
> > > > > I'd be happy to review your pull request once you've squashed the
> > > various
> > > > > bugs.
> > > > >
> > > > > Cheers,
> > > > > Michael
> > > > >
> > > > > On Tue, Nov 4, 2014 at 3:54 AM, Andrey Kurdumov <
> > > kant2002@googlemail.com
> > > > >
> > > > > wrote:
> > > > >
> > > > > > I also find that links in Guides is missing. Not yet sure why is
> > that
> > > > > > looking into that.
> > > > > > Issue which Shazron discover should be fixed now.
> > > > > >
> > > > > > 2014-11-04 3:00 GMT+06:00 Michal Mocny <mm...@chromium.org>:
> > > > > >
> > > > > > > Just tried it using the steps Shaz listed on the PR and its
> > working
> > > > for
> > > > > > me
> > > > > > > fine. However, there are some warnings during generation
> (bunch
> > of
> > > > > "Did
> > > > > > > not found link for the keyword"), and the generated pages
> appear
> > to
> > > > > have
> > > > > > > some links missing (such as the first page, Guides do not link
> to
> > > > > > > anything). Unsure if the warning is the cause of the missing
> > > links.
> > > > > > >
> > > > > > > Keep chugging away!
> > > > > > >
> > > > > > > -Michal
> > > > > > >
> > > > > > > On Mon, Nov 3, 2014 at 2:39 PM, Andrew Grieve <
> > > agrieve@chromium.org>
> > > > > > > wrote:
> > > > > > >
> > > > > > > > Love that you're working on this!
> > > > > > > >
> > > > > > > > On Mon, Nov 3, 2014 at 12:57 AM, Shazron <sh...@gmail.com>
> > > > wrote:
> > > > > > > >
> > > > > > > > > Thanks Andrey,
> > > > > > > > > I tested it out but I ran into problems. See my comment on
> > your
> > > > > pull
> > > > > > > > > request.
> > > > > > > > >
> > > > > > > > > On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <
> > > > > > > kant2002@googlemail.com
> > > > > > > > >
> > > > > > > > > wrote:
> > > > > > > > >
> > > > > > > > > > Hello guys,
> > > > > > > > > >
> > > > > > > > > > I almost finish implementing
> > > > > > > > > > https://issues.apache.org/jira/browse/CB-6751
> > > > > > > > > >
> > > > > > > > > > In short this is implementation of Cordova Docs website
> > > > generator
> > > > > > > using
> > > > > > > > > > Node.JS instead of relying on Vagrant and Ruby.
> > > > > > > > > >
> > > > > > > > > > Summary of work:
> > > > > > > > > > - Implementation duplicates Ruby code as much as
> possible.
> > > > Tests
> > > > > > > which
> > > > > > > > > was
> > > > > > > > > > written for Ruby, was reimplemented in JS.
> > > > > > > > > > - Created new executable genjs in the bin folder, which
> > > > generate
> > > > > > > > > > documentation to the *public/test* folder, instead of
> > > *public*
> > > > > > > folder,
> > > > > > > > so
> > > > > > > > > > differences between implementation could be found using
> > > > standard
> > > > > > > > diffing
> > > > > > > > > > tools.
> > > > > > > > > > - Implementation verified on Mac and Windows.
> > > > > > > > > > - Small improvements to CLI interface (single language
> > > > > generation,
> > > > > > > > single
> > > > > > > > > > version generation, added verbose mode for tracing
> > execution)
> > > > > > > > > > - As I can tell, JS implementation produce almost same
> HTML
> > > > code
> > > > > as
> > > > > > > > Ruby
> > > > > > > > > > version. I done some smoke testing of changes and seems
> > that
> > > > > > > everything
> > > > > > > > > is
> > > > > > > > > > good, but willing that you guys look at the docs too.
> > > > > > > > > >
> > > > > > > > > > To make this works with existing documentation and
> support
> > > > > > Windows, I
> > > > > > > > > have
> > > > > > > > > > to fork existing implementation of joDoc-js (
> > > > > > > > > > https://github.com/kant2002/jodoc-js)
> > > > > > > > > >
> > > > > > > > > > Issues:
> > > > > > > > > > - Windows suffer from occasional EPERM issues during
> > > generation
> > > > > of
> > > > > > > the
> > > > > > > > > > docs.
> > > > > > > > > >
> > > > > > > > > > Pull request for that implementation is here:
> > > > > > > > > > https://github.com/apache/cordova-docs/pull/236
> > > > > > > > > >
> > > > > > > > > > Best regards,
> > > > > > > > > > Andrey
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: Documentation generation in pure Node.JS
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
Andrey, you're approach sounds incredibly thorough! I'll set aside some
time to test your pull request and see how it runs on my system. Today is
already full, so I'll try to have some time set aside for tomorrow or the
weekend.
If anyone else is available to test it, that would be great as well!
https://github.com/apache/cordova-docs/pull/236
Michael
On Wed, Dec 10, 2014 at 7:37 PM, Andrey Kurdumov <ka...@googlemail.com>
wrote:
> Thanks,
> 1. Already play with marked options and don't find any way to resolve that
> using that path. Now I done following:
> a) Generate latest docs using Ruby & JS
> b) Made changes to the original MD files, so previously generated
> version with Ruby will match with generated using JS
> c) Regenerate Ruby version against changed MD files and verify that
> docs still the same as it was originally.
> I made changes to MD files so all languages produce identical results
> Original MD + Ruby <==> Modified MD + JS <==> Modified MD + Ruby
> Most of the changes is inserting or removing blank lines, and most of
> changes is duplication of same place in the MD file, which was caused by
> copying file to new version.
>
> NOTE for documentation writers, Section header should be separated by two
> lines most of the time for documentation to be correctly generated.
>
> 2. Then prefer to drop generation for that _index.json.
>
> I'm fully ready for this pull request to be merged, I don't see now any
> piece of docs that different from original.
>
> 2014-12-08 23:22 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
>
> > Hi Andrey,
> >
> > 1. marked is certainly the most popular and active markdown generate for
> > node. You may want to consider playing around with the options it offers.
> >
> > 2. _index.json was produced by the original joDoc generator, so the
> > node-version may not support it. To the best of my knowledge, no one uses
> > the JSON interface, which was intended to act as a simple API to the
> > documentation.
> >
> > Nice work!
> > Michael
> >
> > On Sat, Dec 6, 2014 at 11:00 AM, Andrey Kurdumov <
> kant2002@googlemail.com>
> > wrote:
> >
> > > Hi all,
> > >
> > > Bumping this thread again, since looks like I almost finish port Ruby
> > > version of documents generation to JS.
> > > I fix issues which you discover last time, and create validation script
> > > which theoretically could spot differences between old version and new
> > one.
> > > So far everything looks good except following 2 items:
> > >
> > > 1. JS version of Markdown parser currently in use is more strict then
> > Ruby
> > > version (Used NPM module *marked*). This results that some small subset
> > of
> > > files produce not identical output in those places where nested lists
> are
> > > used. This could be fixed by adding or removing empty lines. I'm not
> sure
> > > should I change original MD files, or search for better Markdown
> parser.
> > If
> > > somebody know better MD parser I would appreciate pointing on it.
> > > 2. In original docs some unknown _index.json file. Does anybody know
> who
> > is
> > > producing this file and how it is generated, so I could duplicate it
> > > generation too.
> > >
> > > I sure that this is what only thing which prevent me from thinking that
> > > everything is done.
> > >
> > > Best regards,
> > > Andrey
> > >
> > >
> > > 2014-11-04 23:33 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
> > >
> > > > Hi Audrey,
> > > >
> > > > Thanks for tackling this issue!
> > > >
> > > > Truth be told, we want to move away from jsdoc entirely. Years ago,
> we
> > > > thought that the auto-linking and other auto-magical aspects of jsdoc
> > > would
> > > > be nice, but it's caused more problems than good. The ruby
> environment
> > is
> > > > also troublesome, although we've largely solved that with a Vagrant
> > > image.
> > > >
> > > > However, it sounds as though you've managed to re-implement all of
> the
> > > > original middleware that we created. If you're confident that the
> docs
> > > will
> > > > generate the same as before, then I think we'd happily welcome a
> > > pure-node
> > > > documentation generator. I think we will be moving to a different doc
> > > > generation approach in the future, but your re-implementation will
> be a
> > > > great transitional step!
> > > >
> > > > I'd be happy to review your pull request once you've squashed the
> > various
> > > > bugs.
> > > >
> > > > Cheers,
> > > > Michael
> > > >
> > > > On Tue, Nov 4, 2014 at 3:54 AM, Andrey Kurdumov <
> > kant2002@googlemail.com
> > > >
> > > > wrote:
> > > >
> > > > > I also find that links in Guides is missing. Not yet sure why is
> that
> > > > > looking into that.
> > > > > Issue which Shazron discover should be fixed now.
> > > > >
> > > > > 2014-11-04 3:00 GMT+06:00 Michal Mocny <mm...@chromium.org>:
> > > > >
> > > > > > Just tried it using the steps Shaz listed on the PR and its
> working
> > > for
> > > > > me
> > > > > > fine. However, there are some warnings during generation (bunch
> of
> > > > "Did
> > > > > > not found link for the keyword"), and the generated pages appear
> to
> > > > have
> > > > > > some links missing (such as the first page, Guides do not link to
> > > > > > anything). Unsure if the warning is the cause of the missing
> > links.
> > > > > >
> > > > > > Keep chugging away!
> > > > > >
> > > > > > -Michal
> > > > > >
> > > > > > On Mon, Nov 3, 2014 at 2:39 PM, Andrew Grieve <
> > agrieve@chromium.org>
> > > > > > wrote:
> > > > > >
> > > > > > > Love that you're working on this!
> > > > > > >
> > > > > > > On Mon, Nov 3, 2014 at 12:57 AM, Shazron <sh...@gmail.com>
> > > wrote:
> > > > > > >
> > > > > > > > Thanks Andrey,
> > > > > > > > I tested it out but I ran into problems. See my comment on
> your
> > > > pull
> > > > > > > > request.
> > > > > > > >
> > > > > > > > On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <
> > > > > > kant2002@googlemail.com
> > > > > > > >
> > > > > > > > wrote:
> > > > > > > >
> > > > > > > > > Hello guys,
> > > > > > > > >
> > > > > > > > > I almost finish implementing
> > > > > > > > > https://issues.apache.org/jira/browse/CB-6751
> > > > > > > > >
> > > > > > > > > In short this is implementation of Cordova Docs website
> > > generator
> > > > > > using
> > > > > > > > > Node.JS instead of relying on Vagrant and Ruby.
> > > > > > > > >
> > > > > > > > > Summary of work:
> > > > > > > > > - Implementation duplicates Ruby code as much as possible.
> > > Tests
> > > > > > which
> > > > > > > > was
> > > > > > > > > written for Ruby, was reimplemented in JS.
> > > > > > > > > - Created new executable genjs in the bin folder, which
> > > generate
> > > > > > > > > documentation to the *public/test* folder, instead of
> > *public*
> > > > > > folder,
> > > > > > > so
> > > > > > > > > differences between implementation could be found using
> > > standard
> > > > > > > diffing
> > > > > > > > > tools.
> > > > > > > > > - Implementation verified on Mac and Windows.
> > > > > > > > > - Small improvements to CLI interface (single language
> > > > generation,
> > > > > > > single
> > > > > > > > > version generation, added verbose mode for tracing
> execution)
> > > > > > > > > - As I can tell, JS implementation produce almost same HTML
> > > code
> > > > as
> > > > > > > Ruby
> > > > > > > > > version. I done some smoke testing of changes and seems
> that
> > > > > > everything
> > > > > > > > is
> > > > > > > > > good, but willing that you guys look at the docs too.
> > > > > > > > >
> > > > > > > > > To make this works with existing documentation and support
> > > > > Windows, I
> > > > > > > > have
> > > > > > > > > to fork existing implementation of joDoc-js (
> > > > > > > > > https://github.com/kant2002/jodoc-js)
> > > > > > > > >
> > > > > > > > > Issues:
> > > > > > > > > - Windows suffer from occasional EPERM issues during
> > generation
> > > > of
> > > > > > the
> > > > > > > > > docs.
> > > > > > > > >
> > > > > > > > > Pull request for that implementation is here:
> > > > > > > > > https://github.com/apache/cordova-docs/pull/236
> > > > > > > > >
> > > > > > > > > Best regards,
> > > > > > > > > Andrey
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: Documentation generation in pure Node.JS
Posted by Andrey Kurdumov <ka...@googlemail.com>.
Thanks,
1. Already play with marked options and don't find any way to resolve that
using that path. Now I done following:
a) Generate latest docs using Ruby & JS
b) Made changes to the original MD files, so previously generated
version with Ruby will match with generated using JS
c) Regenerate Ruby version against changed MD files and verify that
docs still the same as it was originally.
I made changes to MD files so all languages produce identical results
Original MD + Ruby <==> Modified MD + JS <==> Modified MD + Ruby
Most of the changes is inserting or removing blank lines, and most of
changes is duplication of same place in the MD file, which was caused by
copying file to new version.
NOTE for documentation writers, Section header should be separated by two
lines most of the time for documentation to be correctly generated.
2. Then prefer to drop generation for that _index.json.
I'm fully ready for this pull request to be merged, I don't see now any
piece of docs that different from original.
2014-12-08 23:22 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
> Hi Andrey,
>
> 1. marked is certainly the most popular and active markdown generate for
> node. You may want to consider playing around with the options it offers.
>
> 2. _index.json was produced by the original joDoc generator, so the
> node-version may not support it. To the best of my knowledge, no one uses
> the JSON interface, which was intended to act as a simple API to the
> documentation.
>
> Nice work!
> Michael
>
> On Sat, Dec 6, 2014 at 11:00 AM, Andrey Kurdumov <ka...@googlemail.com>
> wrote:
>
> > Hi all,
> >
> > Bumping this thread again, since looks like I almost finish port Ruby
> > version of documents generation to JS.
> > I fix issues which you discover last time, and create validation script
> > which theoretically could spot differences between old version and new
> one.
> > So far everything looks good except following 2 items:
> >
> > 1. JS version of Markdown parser currently in use is more strict then
> Ruby
> > version (Used NPM module *marked*). This results that some small subset
> of
> > files produce not identical output in those places where nested lists are
> > used. This could be fixed by adding or removing empty lines. I'm not sure
> > should I change original MD files, or search for better Markdown parser.
> If
> > somebody know better MD parser I would appreciate pointing on it.
> > 2. In original docs some unknown _index.json file. Does anybody know who
> is
> > producing this file and how it is generated, so I could duplicate it
> > generation too.
> >
> > I sure that this is what only thing which prevent me from thinking that
> > everything is done.
> >
> > Best regards,
> > Andrey
> >
> >
> > 2014-11-04 23:33 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
> >
> > > Hi Audrey,
> > >
> > > Thanks for tackling this issue!
> > >
> > > Truth be told, we want to move away from jsdoc entirely. Years ago, we
> > > thought that the auto-linking and other auto-magical aspects of jsdoc
> > would
> > > be nice, but it's caused more problems than good. The ruby environment
> is
> > > also troublesome, although we've largely solved that with a Vagrant
> > image.
> > >
> > > However, it sounds as though you've managed to re-implement all of the
> > > original middleware that we created. If you're confident that the docs
> > will
> > > generate the same as before, then I think we'd happily welcome a
> > pure-node
> > > documentation generator. I think we will be moving to a different doc
> > > generation approach in the future, but your re-implementation will be a
> > > great transitional step!
> > >
> > > I'd be happy to review your pull request once you've squashed the
> various
> > > bugs.
> > >
> > > Cheers,
> > > Michael
> > >
> > > On Tue, Nov 4, 2014 at 3:54 AM, Andrey Kurdumov <
> kant2002@googlemail.com
> > >
> > > wrote:
> > >
> > > > I also find that links in Guides is missing. Not yet sure why is that
> > > > looking into that.
> > > > Issue which Shazron discover should be fixed now.
> > > >
> > > > 2014-11-04 3:00 GMT+06:00 Michal Mocny <mm...@chromium.org>:
> > > >
> > > > > Just tried it using the steps Shaz listed on the PR and its working
> > for
> > > > me
> > > > > fine. However, there are some warnings during generation (bunch of
> > > "Did
> > > > > not found link for the keyword"), and the generated pages appear to
> > > have
> > > > > some links missing (such as the first page, Guides do not link to
> > > > > anything). Unsure if the warning is the cause of the missing
> links.
> > > > >
> > > > > Keep chugging away!
> > > > >
> > > > > -Michal
> > > > >
> > > > > On Mon, Nov 3, 2014 at 2:39 PM, Andrew Grieve <
> agrieve@chromium.org>
> > > > > wrote:
> > > > >
> > > > > > Love that you're working on this!
> > > > > >
> > > > > > On Mon, Nov 3, 2014 at 12:57 AM, Shazron <sh...@gmail.com>
> > wrote:
> > > > > >
> > > > > > > Thanks Andrey,
> > > > > > > I tested it out but I ran into problems. See my comment on your
> > > pull
> > > > > > > request.
> > > > > > >
> > > > > > > On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <
> > > > > kant2002@googlemail.com
> > > > > > >
> > > > > > > wrote:
> > > > > > >
> > > > > > > > Hello guys,
> > > > > > > >
> > > > > > > > I almost finish implementing
> > > > > > > > https://issues.apache.org/jira/browse/CB-6751
> > > > > > > >
> > > > > > > > In short this is implementation of Cordova Docs website
> > generator
> > > > > using
> > > > > > > > Node.JS instead of relying on Vagrant and Ruby.
> > > > > > > >
> > > > > > > > Summary of work:
> > > > > > > > - Implementation duplicates Ruby code as much as possible.
> > Tests
> > > > > which
> > > > > > > was
> > > > > > > > written for Ruby, was reimplemented in JS.
> > > > > > > > - Created new executable genjs in the bin folder, which
> > generate
> > > > > > > > documentation to the *public/test* folder, instead of
> *public*
> > > > > folder,
> > > > > > so
> > > > > > > > differences between implementation could be found using
> > standard
> > > > > > diffing
> > > > > > > > tools.
> > > > > > > > - Implementation verified on Mac and Windows.
> > > > > > > > - Small improvements to CLI interface (single language
> > > generation,
> > > > > > single
> > > > > > > > version generation, added verbose mode for tracing execution)
> > > > > > > > - As I can tell, JS implementation produce almost same HTML
> > code
> > > as
> > > > > > Ruby
> > > > > > > > version. I done some smoke testing of changes and seems that
> > > > > everything
> > > > > > > is
> > > > > > > > good, but willing that you guys look at the docs too.
> > > > > > > >
> > > > > > > > To make this works with existing documentation and support
> > > > Windows, I
> > > > > > > have
> > > > > > > > to fork existing implementation of joDoc-js (
> > > > > > > > https://github.com/kant2002/jodoc-js)
> > > > > > > >
> > > > > > > > Issues:
> > > > > > > > - Windows suffer from occasional EPERM issues during
> generation
> > > of
> > > > > the
> > > > > > > > docs.
> > > > > > > >
> > > > > > > > Pull request for that implementation is here:
> > > > > > > > https://github.com/apache/cordova-docs/pull/236
> > > > > > > >
> > > > > > > > Best regards,
> > > > > > > > Andrey
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: Documentation generation in pure Node.JS
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
Hi Andrey,
1. marked is certainly the most popular and active markdown generate for
node. You may want to consider playing around with the options it offers.
2. _index.json was produced by the original joDoc generator, so the
node-version may not support it. To the best of my knowledge, no one uses
the JSON interface, which was intended to act as a simple API to the
documentation.
Nice work!
Michael
On Sat, Dec 6, 2014 at 11:00 AM, Andrey Kurdumov <ka...@googlemail.com>
wrote:
> Hi all,
>
> Bumping this thread again, since looks like I almost finish port Ruby
> version of documents generation to JS.
> I fix issues which you discover last time, and create validation script
> which theoretically could spot differences between old version and new one.
> So far everything looks good except following 2 items:
>
> 1. JS version of Markdown parser currently in use is more strict then Ruby
> version (Used NPM module *marked*). This results that some small subset of
> files produce not identical output in those places where nested lists are
> used. This could be fixed by adding or removing empty lines. I'm not sure
> should I change original MD files, or search for better Markdown parser. If
> somebody know better MD parser I would appreciate pointing on it.
> 2. In original docs some unknown _index.json file. Does anybody know who is
> producing this file and how it is generated, so I could duplicate it
> generation too.
>
> I sure that this is what only thing which prevent me from thinking that
> everything is done.
>
> Best regards,
> Andrey
>
>
> 2014-11-04 23:33 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
>
> > Hi Audrey,
> >
> > Thanks for tackling this issue!
> >
> > Truth be told, we want to move away from jsdoc entirely. Years ago, we
> > thought that the auto-linking and other auto-magical aspects of jsdoc
> would
> > be nice, but it's caused more problems than good. The ruby environment is
> > also troublesome, although we've largely solved that with a Vagrant
> image.
> >
> > However, it sounds as though you've managed to re-implement all of the
> > original middleware that we created. If you're confident that the docs
> will
> > generate the same as before, then I think we'd happily welcome a
> pure-node
> > documentation generator. I think we will be moving to a different doc
> > generation approach in the future, but your re-implementation will be a
> > great transitional step!
> >
> > I'd be happy to review your pull request once you've squashed the various
> > bugs.
> >
> > Cheers,
> > Michael
> >
> > On Tue, Nov 4, 2014 at 3:54 AM, Andrey Kurdumov <kant2002@googlemail.com
> >
> > wrote:
> >
> > > I also find that links in Guides is missing. Not yet sure why is that
> > > looking into that.
> > > Issue which Shazron discover should be fixed now.
> > >
> > > 2014-11-04 3:00 GMT+06:00 Michal Mocny <mm...@chromium.org>:
> > >
> > > > Just tried it using the steps Shaz listed on the PR and its working
> for
> > > me
> > > > fine. However, there are some warnings during generation (bunch of
> > "Did
> > > > not found link for the keyword"), and the generated pages appear to
> > have
> > > > some links missing (such as the first page, Guides do not link to
> > > > anything). Unsure if the warning is the cause of the missing links.
> > > >
> > > > Keep chugging away!
> > > >
> > > > -Michal
> > > >
> > > > On Mon, Nov 3, 2014 at 2:39 PM, Andrew Grieve <ag...@chromium.org>
> > > > wrote:
> > > >
> > > > > Love that you're working on this!
> > > > >
> > > > > On Mon, Nov 3, 2014 at 12:57 AM, Shazron <sh...@gmail.com>
> wrote:
> > > > >
> > > > > > Thanks Andrey,
> > > > > > I tested it out but I ran into problems. See my comment on your
> > pull
> > > > > > request.
> > > > > >
> > > > > > On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <
> > > > kant2002@googlemail.com
> > > > > >
> > > > > > wrote:
> > > > > >
> > > > > > > Hello guys,
> > > > > > >
> > > > > > > I almost finish implementing
> > > > > > > https://issues.apache.org/jira/browse/CB-6751
> > > > > > >
> > > > > > > In short this is implementation of Cordova Docs website
> generator
> > > > using
> > > > > > > Node.JS instead of relying on Vagrant and Ruby.
> > > > > > >
> > > > > > > Summary of work:
> > > > > > > - Implementation duplicates Ruby code as much as possible.
> Tests
> > > > which
> > > > > > was
> > > > > > > written for Ruby, was reimplemented in JS.
> > > > > > > - Created new executable genjs in the bin folder, which
> generate
> > > > > > > documentation to the *public/test* folder, instead of *public*
> > > > folder,
> > > > > so
> > > > > > > differences between implementation could be found using
> standard
> > > > > diffing
> > > > > > > tools.
> > > > > > > - Implementation verified on Mac and Windows.
> > > > > > > - Small improvements to CLI interface (single language
> > generation,
> > > > > single
> > > > > > > version generation, added verbose mode for tracing execution)
> > > > > > > - As I can tell, JS implementation produce almost same HTML
> code
> > as
> > > > > Ruby
> > > > > > > version. I done some smoke testing of changes and seems that
> > > > everything
> > > > > > is
> > > > > > > good, but willing that you guys look at the docs too.
> > > > > > >
> > > > > > > To make this works with existing documentation and support
> > > Windows, I
> > > > > > have
> > > > > > > to fork existing implementation of joDoc-js (
> > > > > > > https://github.com/kant2002/jodoc-js)
> > > > > > >
> > > > > > > Issues:
> > > > > > > - Windows suffer from occasional EPERM issues during generation
> > of
> > > > the
> > > > > > > docs.
> > > > > > >
> > > > > > > Pull request for that implementation is here:
> > > > > > > https://github.com/apache/cordova-docs/pull/236
> > > > > > >
> > > > > > > Best regards,
> > > > > > > Andrey
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: Documentation generation in pure Node.JS
Posted by Andrey Kurdumov <ka...@googlemail.com>.
Hi all,
Bumping this thread again, since looks like I almost finish port Ruby
version of documents generation to JS.
I fix issues which you discover last time, and create validation script
which theoretically could spot differences between old version and new one.
So far everything looks good except following 2 items:
1. JS version of Markdown parser currently in use is more strict then Ruby
version (Used NPM module *marked*). This results that some small subset of
files produce not identical output in those places where nested lists are
used. This could be fixed by adding or removing empty lines. I'm not sure
should I change original MD files, or search for better Markdown parser. If
somebody know better MD parser I would appreciate pointing on it.
2. In original docs some unknown _index.json file. Does anybody know who is
producing this file and how it is generated, so I could duplicate it
generation too.
I sure that this is what only thing which prevent me from thinking that
everything is done.
Best regards,
Andrey
2014-11-04 23:33 GMT+06:00 Michael Brooks <mi...@michaelbrooks.ca>:
> Hi Audrey,
>
> Thanks for tackling this issue!
>
> Truth be told, we want to move away from jsdoc entirely. Years ago, we
> thought that the auto-linking and other auto-magical aspects of jsdoc would
> be nice, but it's caused more problems than good. The ruby environment is
> also troublesome, although we've largely solved that with a Vagrant image.
>
> However, it sounds as though you've managed to re-implement all of the
> original middleware that we created. If you're confident that the docs will
> generate the same as before, then I think we'd happily welcome a pure-node
> documentation generator. I think we will be moving to a different doc
> generation approach in the future, but your re-implementation will be a
> great transitional step!
>
> I'd be happy to review your pull request once you've squashed the various
> bugs.
>
> Cheers,
> Michael
>
> On Tue, Nov 4, 2014 at 3:54 AM, Andrey Kurdumov <ka...@googlemail.com>
> wrote:
>
> > I also find that links in Guides is missing. Not yet sure why is that
> > looking into that.
> > Issue which Shazron discover should be fixed now.
> >
> > 2014-11-04 3:00 GMT+06:00 Michal Mocny <mm...@chromium.org>:
> >
> > > Just tried it using the steps Shaz listed on the PR and its working for
> > me
> > > fine. However, there are some warnings during generation (bunch of
> "Did
> > > not found link for the keyword"), and the generated pages appear to
> have
> > > some links missing (such as the first page, Guides do not link to
> > > anything). Unsure if the warning is the cause of the missing links.
> > >
> > > Keep chugging away!
> > >
> > > -Michal
> > >
> > > On Mon, Nov 3, 2014 at 2:39 PM, Andrew Grieve <ag...@chromium.org>
> > > wrote:
> > >
> > > > Love that you're working on this!
> > > >
> > > > On Mon, Nov 3, 2014 at 12:57 AM, Shazron <sh...@gmail.com> wrote:
> > > >
> > > > > Thanks Andrey,
> > > > > I tested it out but I ran into problems. See my comment on your
> pull
> > > > > request.
> > > > >
> > > > > On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <
> > > kant2002@googlemail.com
> > > > >
> > > > > wrote:
> > > > >
> > > > > > Hello guys,
> > > > > >
> > > > > > I almost finish implementing
> > > > > > https://issues.apache.org/jira/browse/CB-6751
> > > > > >
> > > > > > In short this is implementation of Cordova Docs website generator
> > > using
> > > > > > Node.JS instead of relying on Vagrant and Ruby.
> > > > > >
> > > > > > Summary of work:
> > > > > > - Implementation duplicates Ruby code as much as possible. Tests
> > > which
> > > > > was
> > > > > > written for Ruby, was reimplemented in JS.
> > > > > > - Created new executable genjs in the bin folder, which generate
> > > > > > documentation to the *public/test* folder, instead of *public*
> > > folder,
> > > > so
> > > > > > differences between implementation could be found using standard
> > > > diffing
> > > > > > tools.
> > > > > > - Implementation verified on Mac and Windows.
> > > > > > - Small improvements to CLI interface (single language
> generation,
> > > > single
> > > > > > version generation, added verbose mode for tracing execution)
> > > > > > - As I can tell, JS implementation produce almost same HTML code
> as
> > > > Ruby
> > > > > > version. I done some smoke testing of changes and seems that
> > > everything
> > > > > is
> > > > > > good, but willing that you guys look at the docs too.
> > > > > >
> > > > > > To make this works with existing documentation and support
> > Windows, I
> > > > > have
> > > > > > to fork existing implementation of joDoc-js (
> > > > > > https://github.com/kant2002/jodoc-js)
> > > > > >
> > > > > > Issues:
> > > > > > - Windows suffer from occasional EPERM issues during generation
> of
> > > the
> > > > > > docs.
> > > > > >
> > > > > > Pull request for that implementation is here:
> > > > > > https://github.com/apache/cordova-docs/pull/236
> > > > > >
> > > > > > Best regards,
> > > > > > Andrey
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: Documentation generation in pure Node.JS
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
Hi Audrey,
Thanks for tackling this issue!
Truth be told, we want to move away from jsdoc entirely. Years ago, we
thought that the auto-linking and other auto-magical aspects of jsdoc would
be nice, but it's caused more problems than good. The ruby environment is
also troublesome, although we've largely solved that with a Vagrant image.
However, it sounds as though you've managed to re-implement all of the
original middleware that we created. If you're confident that the docs will
generate the same as before, then I think we'd happily welcome a pure-node
documentation generator. I think we will be moving to a different doc
generation approach in the future, but your re-implementation will be a
great transitional step!
I'd be happy to review your pull request once you've squashed the various
bugs.
Cheers,
Michael
On Tue, Nov 4, 2014 at 3:54 AM, Andrey Kurdumov <ka...@googlemail.com>
wrote:
> I also find that links in Guides is missing. Not yet sure why is that
> looking into that.
> Issue which Shazron discover should be fixed now.
>
> 2014-11-04 3:00 GMT+06:00 Michal Mocny <mm...@chromium.org>:
>
> > Just tried it using the steps Shaz listed on the PR and its working for
> me
> > fine. However, there are some warnings during generation (bunch of "Did
> > not found link for the keyword"), and the generated pages appear to have
> > some links missing (such as the first page, Guides do not link to
> > anything). Unsure if the warning is the cause of the missing links.
> >
> > Keep chugging away!
> >
> > -Michal
> >
> > On Mon, Nov 3, 2014 at 2:39 PM, Andrew Grieve <ag...@chromium.org>
> > wrote:
> >
> > > Love that you're working on this!
> > >
> > > On Mon, Nov 3, 2014 at 12:57 AM, Shazron <sh...@gmail.com> wrote:
> > >
> > > > Thanks Andrey,
> > > > I tested it out but I ran into problems. See my comment on your pull
> > > > request.
> > > >
> > > > On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <
> > kant2002@googlemail.com
> > > >
> > > > wrote:
> > > >
> > > > > Hello guys,
> > > > >
> > > > > I almost finish implementing
> > > > > https://issues.apache.org/jira/browse/CB-6751
> > > > >
> > > > > In short this is implementation of Cordova Docs website generator
> > using
> > > > > Node.JS instead of relying on Vagrant and Ruby.
> > > > >
> > > > > Summary of work:
> > > > > - Implementation duplicates Ruby code as much as possible. Tests
> > which
> > > > was
> > > > > written for Ruby, was reimplemented in JS.
> > > > > - Created new executable genjs in the bin folder, which generate
> > > > > documentation to the *public/test* folder, instead of *public*
> > folder,
> > > so
> > > > > differences between implementation could be found using standard
> > > diffing
> > > > > tools.
> > > > > - Implementation verified on Mac and Windows.
> > > > > - Small improvements to CLI interface (single language generation,
> > > single
> > > > > version generation, added verbose mode for tracing execution)
> > > > > - As I can tell, JS implementation produce almost same HTML code as
> > > Ruby
> > > > > version. I done some smoke testing of changes and seems that
> > everything
> > > > is
> > > > > good, but willing that you guys look at the docs too.
> > > > >
> > > > > To make this works with existing documentation and support
> Windows, I
> > > > have
> > > > > to fork existing implementation of joDoc-js (
> > > > > https://github.com/kant2002/jodoc-js)
> > > > >
> > > > > Issues:
> > > > > - Windows suffer from occasional EPERM issues during generation of
> > the
> > > > > docs.
> > > > >
> > > > > Pull request for that implementation is here:
> > > > > https://github.com/apache/cordova-docs/pull/236
> > > > >
> > > > > Best regards,
> > > > > Andrey
> > > > >
> > > >
> > >
> >
>
Re: Documentation generation in pure Node.JS
Posted by Andrey Kurdumov <ka...@googlemail.com>.
I also find that links in Guides is missing. Not yet sure why is that
looking into that.
Issue which Shazron discover should be fixed now.
2014-11-04 3:00 GMT+06:00 Michal Mocny <mm...@chromium.org>:
> Just tried it using the steps Shaz listed on the PR and its working for me
> fine. However, there are some warnings during generation (bunch of "Did
> not found link for the keyword"), and the generated pages appear to have
> some links missing (such as the first page, Guides do not link to
> anything). Unsure if the warning is the cause of the missing links.
>
> Keep chugging away!
>
> -Michal
>
> On Mon, Nov 3, 2014 at 2:39 PM, Andrew Grieve <ag...@chromium.org>
> wrote:
>
> > Love that you're working on this!
> >
> > On Mon, Nov 3, 2014 at 12:57 AM, Shazron <sh...@gmail.com> wrote:
> >
> > > Thanks Andrey,
> > > I tested it out but I ran into problems. See my comment on your pull
> > > request.
> > >
> > > On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <
> kant2002@googlemail.com
> > >
> > > wrote:
> > >
> > > > Hello guys,
> > > >
> > > > I almost finish implementing
> > > > https://issues.apache.org/jira/browse/CB-6751
> > > >
> > > > In short this is implementation of Cordova Docs website generator
> using
> > > > Node.JS instead of relying on Vagrant and Ruby.
> > > >
> > > > Summary of work:
> > > > - Implementation duplicates Ruby code as much as possible. Tests
> which
> > > was
> > > > written for Ruby, was reimplemented in JS.
> > > > - Created new executable genjs in the bin folder, which generate
> > > > documentation to the *public/test* folder, instead of *public*
> folder,
> > so
> > > > differences between implementation could be found using standard
> > diffing
> > > > tools.
> > > > - Implementation verified on Mac and Windows.
> > > > - Small improvements to CLI interface (single language generation,
> > single
> > > > version generation, added verbose mode for tracing execution)
> > > > - As I can tell, JS implementation produce almost same HTML code as
> > Ruby
> > > > version. I done some smoke testing of changes and seems that
> everything
> > > is
> > > > good, but willing that you guys look at the docs too.
> > > >
> > > > To make this works with existing documentation and support Windows, I
> > > have
> > > > to fork existing implementation of joDoc-js (
> > > > https://github.com/kant2002/jodoc-js)
> > > >
> > > > Issues:
> > > > - Windows suffer from occasional EPERM issues during generation of
> the
> > > > docs.
> > > >
> > > > Pull request for that implementation is here:
> > > > https://github.com/apache/cordova-docs/pull/236
> > > >
> > > > Best regards,
> > > > Andrey
> > > >
> > >
> >
>
Re: Documentation generation in pure Node.JS
Posted by Michal Mocny <mm...@chromium.org>.
Just tried it using the steps Shaz listed on the PR and its working for me
fine. However, there are some warnings during generation (bunch of "Did
not found link for the keyword"), and the generated pages appear to have
some links missing (such as the first page, Guides do not link to
anything). Unsure if the warning is the cause of the missing links.
Keep chugging away!
-Michal
On Mon, Nov 3, 2014 at 2:39 PM, Andrew Grieve <ag...@chromium.org> wrote:
> Love that you're working on this!
>
> On Mon, Nov 3, 2014 at 12:57 AM, Shazron <sh...@gmail.com> wrote:
>
> > Thanks Andrey,
> > I tested it out but I ran into problems. See my comment on your pull
> > request.
> >
> > On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <kant2002@googlemail.com
> >
> > wrote:
> >
> > > Hello guys,
> > >
> > > I almost finish implementing
> > > https://issues.apache.org/jira/browse/CB-6751
> > >
> > > In short this is implementation of Cordova Docs website generator using
> > > Node.JS instead of relying on Vagrant and Ruby.
> > >
> > > Summary of work:
> > > - Implementation duplicates Ruby code as much as possible. Tests which
> > was
> > > written for Ruby, was reimplemented in JS.
> > > - Created new executable genjs in the bin folder, which generate
> > > documentation to the *public/test* folder, instead of *public* folder,
> so
> > > differences between implementation could be found using standard
> diffing
> > > tools.
> > > - Implementation verified on Mac and Windows.
> > > - Small improvements to CLI interface (single language generation,
> single
> > > version generation, added verbose mode for tracing execution)
> > > - As I can tell, JS implementation produce almost same HTML code as
> Ruby
> > > version. I done some smoke testing of changes and seems that everything
> > is
> > > good, but willing that you guys look at the docs too.
> > >
> > > To make this works with existing documentation and support Windows, I
> > have
> > > to fork existing implementation of joDoc-js (
> > > https://github.com/kant2002/jodoc-js)
> > >
> > > Issues:
> > > - Windows suffer from occasional EPERM issues during generation of the
> > > docs.
> > >
> > > Pull request for that implementation is here:
> > > https://github.com/apache/cordova-docs/pull/236
> > >
> > > Best regards,
> > > Andrey
> > >
> >
>
Re: Documentation generation in pure Node.JS
Posted by Andrew Grieve <ag...@chromium.org>.
Love that you're working on this!
On Mon, Nov 3, 2014 at 12:57 AM, Shazron <sh...@gmail.com> wrote:
> Thanks Andrey,
> I tested it out but I ran into problems. See my comment on your pull
> request.
>
> On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <ka...@googlemail.com>
> wrote:
>
> > Hello guys,
> >
> > I almost finish implementing
> > https://issues.apache.org/jira/browse/CB-6751
> >
> > In short this is implementation of Cordova Docs website generator using
> > Node.JS instead of relying on Vagrant and Ruby.
> >
> > Summary of work:
> > - Implementation duplicates Ruby code as much as possible. Tests which
> was
> > written for Ruby, was reimplemented in JS.
> > - Created new executable genjs in the bin folder, which generate
> > documentation to the *public/test* folder, instead of *public* folder, so
> > differences between implementation could be found using standard diffing
> > tools.
> > - Implementation verified on Mac and Windows.
> > - Small improvements to CLI interface (single language generation, single
> > version generation, added verbose mode for tracing execution)
> > - As I can tell, JS implementation produce almost same HTML code as Ruby
> > version. I done some smoke testing of changes and seems that everything
> is
> > good, but willing that you guys look at the docs too.
> >
> > To make this works with existing documentation and support Windows, I
> have
> > to fork existing implementation of joDoc-js (
> > https://github.com/kant2002/jodoc-js)
> >
> > Issues:
> > - Windows suffer from occasional EPERM issues during generation of the
> > docs.
> >
> > Pull request for that implementation is here:
> > https://github.com/apache/cordova-docs/pull/236
> >
> > Best regards,
> > Andrey
> >
>
Re: Documentation generation in pure Node.JS
Posted by Shazron <sh...@gmail.com>.
Thanks Andrey,
I tested it out but I ran into problems. See my comment on your pull
request.
On Sun, Nov 2, 2014 at 1:11 PM, Andrey Kurdumov <ka...@googlemail.com>
wrote:
> Hello guys,
>
> I almost finish implementing
> https://issues.apache.org/jira/browse/CB-6751
>
> In short this is implementation of Cordova Docs website generator using
> Node.JS instead of relying on Vagrant and Ruby.
>
> Summary of work:
> - Implementation duplicates Ruby code as much as possible. Tests which was
> written for Ruby, was reimplemented in JS.
> - Created new executable genjs in the bin folder, which generate
> documentation to the *public/test* folder, instead of *public* folder, so
> differences between implementation could be found using standard diffing
> tools.
> - Implementation verified on Mac and Windows.
> - Small improvements to CLI interface (single language generation, single
> version generation, added verbose mode for tracing execution)
> - As I can tell, JS implementation produce almost same HTML code as Ruby
> version. I done some smoke testing of changes and seems that everything is
> good, but willing that you guys look at the docs too.
>
> To make this works with existing documentation and support Windows, I have
> to fork existing implementation of joDoc-js (
> https://github.com/kant2002/jodoc-js)
>
> Issues:
> - Windows suffer from occasional EPERM issues during generation of the
> docs.
>
> Pull request for that implementation is here:
> https://github.com/apache/cordova-docs/pull/236
>
> Best regards,
> Andrey
>