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 Thu, 11 Dec 2014 17:17:15 GMT
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