Dgeni - Documentation Generation Rework #6232
Conversation
Thanks for the PR! Please check the items below to help us merge this faster. See the contributing docs for more information.
If you need to make changes to your pull request, you can update the commit with Thanks again for your help! |
@@ -105,7 +105,7 @@ function myController($scope, notify) { | |||
</doc:source> | |||
</doc:example> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since many of these remove the doc: namespace, does that mean it's required for all of them?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've added a PR with these changes @ petebacondarwin#3, as the examples look very strange without the change (for instance, http://ci.angularjs.org/job/angular.js-pete/437/artifact/build/docs/guide/filter vs http://docs.angularjs.org/guide/filter)
The generator is able to imply the module from the containing folder for most files but these are in the ng module but are stored at the root folder.
It is safer to use markdown style links and save jsdoc style links for internal links and code references
It is problematic to use {@link} tags with external links because the markdown parser converts them to links for us before we parse the @links. This means that the following tag: ``` {@link http://www.google.com Google} ``` get converted to: ``` {@link <a href="http://www.google.com/"></a> Google} ``` Our {@link} parser then converts this to: ``` <a href="<a"><</a>href="http://www.google.com/"></a> Google} ``` which is clearly a mess. The best solution is not to use {@link} tags for external links and just use the standard markdown syntax: ``` [Google](http://www.google.com) ``` In the long run, we could look into configuring or modifying `marked` not to convert these external links or we could provide a "pre-parser" processor that dealt with such links before `marked` gets its hands on it.
chore(doc-gen): implement dgeni
Even though it is defined in the auto folder, it makes more sense for this function to appear in the ng module in the docs.
The protractor tests were failing because the spans containing the icons were not displaying anymore.
The links to code elements have now changed: api/ng.directive:ngClick -> api/ng/directive/ngClick. Examples now run inside iframes, so we need to instruct Protractor to switch to the example iframe.
Really the doc-gen process should escape there but for now this should stop the layout from breaking.
The task was removed by an earlier commit, and executing it breaks TravisCI builds. It may be replaced at a later date.
…le>... This CL also contains style fixes as the converted scripts caused jshint to complain.
There are no real JQuery tests at this point anyway and the Safari that we are getting from SauceLabs seems to be a flakey Windows 2000 version that is not necessarily providing accurate results.
Here it is.
Still a couple of protractor tests failing but will be sorted out very soon.