cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrey Kurdumov <kant2...@googlemail.com>
Subject Re: Documentation generation in pure Node.JS
Date Sat, 06 Dec 2014 19:00:45 GMT
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
> > > > > >
> > > > >
> > > >
> > >
> >
>

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