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 Thu, 11 Dec 2014 03:37:27 GMT
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
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>

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