Migration to webpack

[b4dnewz]

Project build

A little recap, grunt is old and slower compared to webpack so I proposed to migrate to it.
This is the build setup using webpack, I've also added the browser field to package.json file pointing to the unminified build for the web projects, it's not ready yet to fully replace grunt we must move the documentation generator also... I've tried also to replicate the grunt-documentation plugin using the documentation npm module but the output is quite different and I don't understand why since the options are the same, probably it's because I'm using a newer version.

---

Project documentation

TL;DR DEMO

This is the file I've made for programmatical use of documentationjs, but the output is somehow different :( probably depends of the newer version, but I don't know exactly.

I've created another branch to try out jsdoc with this project and managed to make it work after fixing a couple of tags errors, there are still some checks to do, regards examples and other parts of the documentation to ensure they match the jsdoc standard... but this is a preview of the result.

This is the default theme, if you like this solution we can use the theme you like more.

I think in terms of readability and usability is better than the wiki pages, I admit I'm used to read stuff in github, I spend most of my time on it, but since jsdoc (esdoc, tsdoc and friends) are widely used I feel familiar to move around the documentation generated by that tools.

---

The idea is to migrate the documentation, merge it in the webpack branch and than merge back into v3.1.
What do you think about it?

[coveralls]

Coverage remained the same at 94.817% when pulling 7bff421 on b4dnewz:migration/webpack into c18b945 on glayzzle:master.

[b4dnewz]

I've restored the old grunt/grunt-documentation deps and tried to generate the documentation and the output is different, also I've tried to checkout the master branch and regenerate documentation and the output is still different so I guess the documentation is just old and there are no changes in the plugin, here a sample of a diff:

I guess using this file is cool and I can remove grunt and use documentationjs node api to replace the grunt task.

[ichiriac]

Hi @b4dnewz, I like the JSDoc output but when I have to read that kind of documentation the hard part is that everything is mixed and information is condensed.

I want to provide a simple quick start and don't bother the reader with too technical information about internal functions from the API.

Maybe by using another template could help, like this one https://github.com/braintree/jsdoc-template/ or this one : https://github.com/docstrap/docstrap#readme

Do we can add cookbook pages on JSDoc in order to also provide some mini tutorials ?

If the html output is clean and readable, we may give up the markdown version, no more need to maintain it.

[ichiriac]

great work, it will be really awesome !!

[ichiriac]

👍

[ichiriac]

could you provide extra options ;

• Positions
• Comments
• Extract the source
• Extract tokens
• Failover on errors

[ichiriac]

could you use a JSON formatter like for example https://myst729.github.io/vue-json-tree/ ?

For huge outputs it should be simpler to navigate

[ichiriac]

BTW, I really like to demo, I've tried it online here : https://rawgit.com/b4dnewz/php-parser/migration/webpack/example/index.html

[ichiriac]

👍 ❤️

[ichiriac]

Excellent ! Can I merge ?

[b4dnewz]

hi @ichiriac good morning, I was about to write you, just few minutes because I found in the documentation the tutorials give a 404 caused from a bad href reference.

also i've excluded the docs, tutorials from eslint to avoid codeclimate gets angry :)

[ichiriac]

hi @b4dnewz, good morning :)

I really like the new demo, you have done a great job here !

[b4dnewz]

I've this strange problem now that is making me crazy I don't now why the tutorial files generated by jsdoc are capitalized but when I go to commit them they are lower cased O_o which results in a 404 on documentation href

mysteries of life...

[b4dnewz]

Ok.. I'm not exactly sure how to fix codeclimate I though adding docs folder to eslintignore would fix it but I was wrong.

Talking about the PR this is was I made:

I've updated the demo page including all the parser settings, changed the jsdoc documentation template but as you can see it still needs some customization.

I've added some tutorial pages and references here an example.

It still need to be completed updating the comments pointing the various parts of the code to their relative example/tutorial if any, I took these from the old docs folder.

This branch is behind the master few commits I try to align them and then we can merge if nothing fails.

[ichiriac]

👍

[ichiriac]

all add dist/ folder

[b4dnewz]

Oh jesuss... now I add also test folder

Edit: there is still this

that I'm not exactly sure how to deal with it, I hope codeclimate does not complain too much, it has low priority

[b4dnewz]

Ok I guess if we ignore the codeclimate warning it's ready.

[ichiriac]

It's strange because index.d.ts is not modified by your PR so it should not be considered as a new issue, and also it's a false positive as it's not a duplicate code :

We are ready to go 💯

[ichiriac]

Hi @b4dnewz,

I've merged your PR, and as the demo is really cool so I've published it on glayzzle. You have access over https://github.com/glayzzle/glayzzle.github.io - there you can publish changes as you want

I think it would be better that the example and docs folders are published on the website repository - so I've removed/ignored them from the repository.

In order to release the docs we can run the generatio from this repository and next we copy/paste the docs folder on the website repository, unless you know a better way to achieve this.

[b4dnewz]

hi @ichiriac, usually I create a custom package.json script, for publishing demo pages, with the following command:

git subtree push --prefix demo origin gh-pages`

In our case we can use it to publish the auto generated docs folder, for example in our package.json:

"scripts": {
  "build": "webpack --config webpack.config.js",
  "publish-docs": "git subtree push --prefix docs origin gh-pages"
},

Once we publish a new version or update the docs we run npm run publish-docs and we have the documentation hosted on: https://glayzzle.github.com/php-parser

Do you like that?

[b4dnewz]

Than for the official website the separate repository it's ok and the Documentation link can point to the php-parser gh-pages

[ichiriac]

Yes, it's great, I like it ! This way we'll be able to publish on the various packages 👍

[b4dnewz]

yup, later this evening I'll add the command and publish the first gh-pages with the documentation, ok?
do you want to check some of the markdown tutorials first?

[ichiriac]

I have to rewrite them, but for a first shot it's OK. When your system will be released it will be easy to update them. You can go ahead and move them to gh-pages

Really thanks for your help, without you I'll never get the time to do that sort of user-frendly improvements

[b4dnewz]

no worries, when I have time is always a pleasure to help

[b4dnewz]

@ichiriac i'm proceeding, in order to use git subtree we must trackdocs folder into git and commit it, i've updated the package.json with the files property to include only lib and dist folder so the npm package remains slim, while the github repository is bigger because has all files in it and the gh-pages only the last committed docs folder while subtreeing.

Also, I'm going to setup Algolia DocSearch to enable documentation search as suggested from jsdoc-template, which right now is missing and is quite difficult to navigate the classes, when I've all set up I set your as the owner of that so you can manage and maybe in the future we can use for more documentations, is free (it says)

For now I just subtree push the docs as it is until I've configured everything.

Am I enabled to do it? (pushing/creating branch)

[ichiriac]

yes of course, no problem

[b4dnewz]

Ok I made it, but you probably have to set (or check if it is setted) the gh-pages branch in the repository settings if the 404 doesn't go away in few minutes https://glayzzle.github.io/php-parser

When it's ready I can use it in the Algolia docsearch creation since it needs to parse the html page first.

[b4dnewz]

hi @ichiriac, good evening

I've added the algolia docsearch support as was suggested by the jsdoc theme, here the result. It looks glitchy but depends on the grafic of the theme we are using.

By the way there's no login/account in this algolia docsearch thing, it's a manual review they make after you request it for a specific site and they contacted me by email where they gave me (today) the apikey.

Once is enabled it will be reloaded once a day and updated in their database. That's it.

I've also added a package.json script to publish the documentation with npm run publish-docs which will basically subtree the docs folder into gh-pages

[ichiriac]

Hi @b4dnewz,

The search engine is really helpfull and I like the result display. I hope the opensource plan will be enough but anyway, it's a great feature.

Do you think we could integrate the playground demo as a custom page of the documentation ?

I've forked the template here https://github.com/glayzzle/jsdoc-template, so we will be able to customise or fix css if needed.

[b4dnewz]

Do you think we could integrate the playground demo as a custom page of the documentation ?

Good idea, I will try