cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Brooks <mich...@michaelbrooks.ca>
Subject Re: Documentation generation in pure Node.JS
Date Tue, 04 Nov 2014 17:33:49 GMT
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
> > > > >
> > > >
> > >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message