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 Mon, 08 Dec 2014 17:22:42 GMT
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
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>

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