documentation generator

[Yann Driutti]

Hi,
I have written the doc as in AngularJS code.
I'm looking to generate the doc.
Does somebody know how to generate the doc of my app ?

my example :

/**
 * @ngdoc controller
 * @name squale.controller.myCtrl
 * @function
 *
 * @description
 * Controller custom
 *
 * @param $scope {Scope} le scope de la page de connexion
 * @returns {void} RAS.
 * @example
    <doc:example>
        <doc:source>
            <div ng-controller="myCtrl">
                Hello <input type="text" ng-model="name"/> !
            </div>
            <script>
                function myCtrl($scope) {
                    $scope.name = "Toto";
                }
            </script>
        </doc:source>
        <doc:scenario>
            it('doit tester un scenario', function() {
                expect(element('.doc-example-live div>:input').val()).toBe('Toto');
            });
        </doc:scenario>
    </doc:example>
 */

function myCtrl($scope) {
      $scope.name = "Toto";
 }

Yann

[Andy Joslin]

https://github.com/angular/angular.js/tree/master/docs/src

Specifically https://github.com/angular/angular.js/blob/master/docs/src/gen-docs.js

[Yann Driutti]

Thanks you,

I don't understand
What do I have to do is just calling the gen-docs.js in my app ?
I'm not talking about generate the angularjs doc but my own app doc.
Is it possible to use the doc generator of angular to generate mine ? and how (with the browser, nodejs, with a command...) ?

yann


On Wednesday, February 6, 2013 6:39:08 PM UTC+1, Andy Joslin wrote:

https://github.com/angular/angular.js/tree/master/docs/src

Specifically https://github.com/angular/angular.js/blob/master/docs/src/gen-docs.js

[Andy Joslin]

The easiest way to generate your own docs would be to rip out that docs/src folder and change things around a bit to point to your own src folder, and then run `node gen-docs.js`

[Yann Driutti]

thanks,
i'll try that

[Frédéric Bonjour]

Did you achieve to generate the docs with the gen-docs.js script?

[Yann Driutti]

not yet

i'll try if i find the time... but it seems very interesting for us.

 

thanks

 

 

2013/2/12 Frédéric Bonjour <frederic...@gmail.com>

--
You received this message because you are subscribed to the Google Groups "AngularJS" group.
To unsubscribe from this group and stop receiving emails from it, send an email to angular+u...@googlegroups.com.
To post to this group, send email to ang...@googlegroups.com.
Visit this group at http://groups.google.com/group/angular?hl=en-US.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[John Martin]

Hey Yann,  Did you have success?  I am just about done with a grunt plugin for angular doc generation. I'll post back when it is complete.

[Yann Driutti]

Unfortunatly not...
But i'll be very happy if you share your solution

Yann

[John Martin]

Okay, I should be done within 2 weeks or so. I'll shoot you a message when it's complete.

--
You received this message because you are subscribed to a topic in the Google Groups "AngularJS" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/angular/rlItfQhqlC4/unsubscribe?hl=en-US.
To unsubscribe from this group and all its topics, send an email to angular+u...@googlegroups.com.

[John Martin]

Alright, made some good progress.. wouldn't say it is completely production ready but is stable enough to at least generate and view your own documentation.

I need to add some documentation on its use but it is used as a grunt plugin within node.

https://npmjs.org/package/grunt-docular

The Gruntfile.js  :

module.exports = function(grunt) {

    // Project configuration.

    grunt.initConfig({

        pkg: grunt.file.readJSON('package.json'),

        docular: {

            groups: [],

            showDocularDocs: true,

            showAngularDocs: true

        }

    });

    // Load the plugin that provides the "uglify" task.

    grunt.loadNpmTasks('grunt-docular');

    // Default task(s).

    grunt.registerTask('default', ['docular']);

};

then I run "grunt"  to generate the documentation and when it completes you run "grunt docular-server". I added configs so it will generate documentation on the original angular source and the starts of the documentation for docular.  If you want to run it against your own code, that would go into groups... this is what the group looks like for angular (you would simply copy this basic format): "Scripts" are folders or files that have the docs within the comments of a script file (this is probably what most people will use). "Docs" are files or folders that contain files where the docs are not in comments (not prefixed with /** or * ).

{

    groupTitle: 'Angular Docs', //this is what will show up in the UI for this group

    groupId: 'angular', //to determine what directory these docs will go into and used as an identifier

    groupIcon: 'icon-book', //icon to use when relevant and within this group of documentation

    sections: [

        {

            id: "api",

            title:"Angular API",

            scripts: ["lib/angular/js"]

        },

        {

            id: "guide",

            title: "Developers Guide",

            docs: ["lib/angular/ngdocs/guide"]

        },

        {

            id: "tutorial",

            title: "Tutorial",

            docs: ["lib/angular/ngdocs/tutorial"]

        },

        {

            id: "misc",

            title: "Overview",

            docs: ["lib/angular/ngdocs/misc"]

        }

    ]

}

Let me know if you run into any issues.. i had some bugs that I think I fixed for node on Windows.

I'll post back when I update the documentation... probably this weekend.

On Tuesday, April 9, 2013 8:54:13 AM UTC-7, John Martin wrote:

Okay, I should be done within 2 weeks or so. I'll shoot you a message when it's complete.

On Tue, Apr 9, 2013 at 3:27 AM, Yann Driutti <ydri...@gmail.com> wrote:

Unfortunatly not...
But i'll be very happy if you share your solution

Yann

--
You received this message because you are subscribed to a topic in the Google Groups "AngularJS" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/angular/rlItfQhqlC4/unsubscribe?hl=en-US.

To unsubscribe from this group and all its topics, send an email to angular+unsubscribe@googlegroups.com.

[Yann Driutti]

That's TREMENDOUS !

I really enjoy your work.
I have some questions :
- Is the e2e test generation is included ?
- where can i find a sample of the comment that the generator read to generate the docs ?

for instance, does your generator works with this angular directive ?
https://github.com/angular/angular.js/blob/master/src/ng/directive/ngBind.js

Congratulation for your work and thanks !
Yann

[John Martin]

Yes, good question on the e2e testing. I believe the original Angular doc generation did have some testing setup. I need to go back and wire all of that up. Thanks Yann.

Since this project started with the original scripts from Angular's doc generation, it is completely compatible with the AngularJS source. In fact, I kept the Angular source in the project and added a flag to include it in the documentation generation and rendering.  I need to add more documentation on how the documentation is generated, but you can use the Angular source as a starting point. I added some documentation for configuring it as a grunt-plugin here:  https://github.com/gitsome/grunt-docular

Keep me posted with any gotchas you come across... I'll be busy working on additional documentation and then the e2e testing.

Yann

--
You received this message because you are subscribed to a topic in the Google Groups "AngularJS" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/angular/rlItfQhqlC4/unsubscribe?hl=en-US.

To unsubscribe from this group and all its topics, send an email to angular+u...@googlegroups.com.

[Valentyn Shybanov]

John, great work.

AngularJS guys made a greate doc generation so I would love to reuse that. May be in future AngularJS devs will separate doc generation source from AngularJS source make Docular more simplier...

Середа, 17 квітня 2013 р. 18:10:09 UTC+3 користувач John Martin написав:

[Lior M]

this is impressive. But trying to use it, i get what looks like a valid output on the console, but can't find the output folder with the documentation! (I looked everywhere, I swear ;)

c:\code\server\prod\ci\client\scripts>grunt docular

in grunt

Running "docular" task

-------- verifying plugins --------

-------- generating Docs --------

Extracting angular Docs For Section "api1"...

Extracting angular Docs For Section "api"...

-------- generating partials directories for groups --------

-------- generating partials directories for sections --------

-------- merging child docs with parent docs --------

BAD LINK: documentation/angular/guide/bootstrap

BAD LINK: documentation/angular/guide/di

BAD LINK: documentation/angular/guide/compiler

...

BAD LINK: documentation/angular/guide/expression

BAD LINK: documentation/angular/guide/expression

-------- generating partials --------

-------- generating supporting files --------

-------- generating index.html page --------

-------- gathering all doc_api, plugin, and configured css and js --------

-------- generating report --------

DONE! Generated 164 pages in 3185 ms. Partials per second : 51

Done, without errors.

the Gruntfile docular config contents:

 docular: {

      baseUrl: 'http://localhost', //base tag used by Angular

      showAngularDocs: false, //parse and render Angular documentation

      showDocularDocs: false, //parse and render Docular documentation

      docAPIOrder : ['api','prod'], //order to load ui resources

      groups: [{

          groupTitle: 'Project Docs', //Title used in the UI

          groupId: 'angular', //identifier and determines directory

          groupIcon: 'icon-book', //Icon to use for this group

          sections: [

              {

                  id: "api1",

                  title:"Prod1",

                  scripts: ["../../../static/app"]

              },

              {

                  id: "api",

                  title:"Angular API",

                  scripts: ["js/src"]

              }

          ]

      }] //groups of documentation to parse

    }

any ideas? thanks very much!!

Lior

[John Martin]

Lior,

Thanks for posting your gruntfile configs. There is work to be done to make finding and customizing the output of the process more user friendly. The output is buried right now deep within the docular npm package.

If you installed grunt-docular, then you can find the generated webapp files here:

/root/node_modules/grunt-docular/node_modules/docular/lib/webapp

That is the entire webapp that is generated, so running "grunt docular-server" starts a nodejs webapp but makes the working directory for that process equal to:

/root/node_modules/grunt-docular/node_modules/docular/lib/webapp

Until the final implementation is complete for exporting the webapp, other people are running a grunt copy command to copy the contents of that folder into their own specified area. Then they are running a node server or apache server against this copied content.

I hope that helps!  There is a big wave of refinement coming so please keep the feedback coming!

John

To unsubscribe from this topic, visit https://groups.google.com/d/topic/angular/rlItfQhqlC4/unsubscribe.

To unsubscribe from this group and all its topics, send an email to angular+u...@googlegroups.com.
To post to this group, send email to ang...@googlegroups.com.

Visit this group at http://groups.google.com/group/angular.

[Lior M]

ohn

thanks so much. Now I understand where this is going, and it looks absolutely amazing: an app for documentation, including search! really like it. only thing is, it still doesnt work for me :).  I cant see anything there... I found that you are using addTag instead, so the links are pointed at localhost, while the server is at port 8000 (127.0.0.1:8000) still searching but  maybe you could throw a quick hint on how to fix. 

BTW: what do u mean by "we can't add css/js the usual way, because some browsers (FF) eagerly prefetch resources

        // before the base attribute is added, causing 404 and terribly slow loading of the docs app." - do u mean baseUrl? 

thanks again

Lior 

[John Martin]

Yeah, the AngularJS team did a killer job getting a nice open source docs generator out there! 

So the comment about "FF eagerly" prefetching resources is a comment from the original AngularJS source and I have not taken a look at this specifically so Docular is utilizing that original source for setting up the index.html page. I will have to investigate this further.

So addTag creates script tags and injects them in the head relative to the root of where index.html lives on the server. So are you getting 404's?  

I do know Docular does not yet work anywhere except at the root of the server due to some complications with loading resources. Is this your situation?

Also, I don't want to pollute this thread, so in the future, anyone with Docular issues can go to github and open issues there:

https://github.com/gitsome/docular or email me directly johnda...@gmail.com

John

[Lior M]

thanks John, will do

[Andy Joslin]

@John, what do you think of grunt-ngdocs? https://github.com/m7r/grunt-ngdocs

Maybe you guys should get together and figure out something :-)