cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Grieve <agri...@chromium.org>
Subject Re: Documentation generation in pure Node.JS
Date Wed, 31 Dec 2014 05:20:23 GMT
Merged!

On Thu, Dec 25, 2014 at 12:02 AM, Andrey Kurdumov <kant2002@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 <agrieve@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 <michael@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
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>

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