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 <agri...@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 <kant2...@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 <mich...@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 < > > kant2...@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 <mich...@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 < > > > > kant2...@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 < > > mich...@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 < > > > > > kant2...@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 <mmo...@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 < > > > > > agri...@chromium.org> > > > > > > > > > wrote: > > > > > > > > > > > > > > > > > > > Love that you're working on this! > > > > > > > > > > > > > > > > > > > > On Mon, Nov 3, 2014 at 12:57 AM, Shazron < > > shaz...@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 < > > > > > > > > > kant2...@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 > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
