documentation generator

Showing 1-21 of 21 messages
documentation generator Yann Driutti 2/6/13 8:14 AM
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
Re: documentation generator Andrew Joslin 2/6/13 9:39 AM
https://github.com/angular/angular.js/tree/master/docs/src

Re: documentation generator Yann Driutti 2/7/13 4:42 AM
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

Re: documentation generator Andrew Joslin 2/7/13 6:25 AM
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`
Re: documentation generator Yann Driutti 2/7/13 6:57 AM
thanks,
i'll try that

Re: documentation generator Frédéric Bonjour 2/12/13 1:39 AM
Did you achieve to generate the docs with the gen-docs.js script?
Re: [AngularJS] Re: documentation generator Yann Driutti 2/14/13 12:56 AM
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.
 
 

Re: [AngularJS] Re: documentation generator John Martin 4/8/13 2:54 PM
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.
Re: [AngularJS] Re: documentation generator Yann Driutti 4/9/13 3:27 AM
Unfortunatly not...
But i'll be very happy if you share your solution

Yann
Re: [AngularJS] Re: documentation generator John Martin 4/9/13 8:54 AM
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.

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.
 
 

Re: [AngularJS] Re: documentation generator John Martin 4/16/13 3:46 PM
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.


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.
Re: [AngularJS] Re: documentation generator Yann Driutti 4/17/13 6:47 AM
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


Re: [AngularJS] Re: documentation generator John Martin 4/17/13 8:10 AM
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.
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.
 
 

Re: [AngularJS] Re: documentation generator Valentyn Shybanov 6/3/13 2:28 AM
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 написав:
Re: [AngularJS] Re: documentation generator Lior M 7/24/13 2:08 PM
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
Re: [AngularJS] Re: documentation generator John Martin 7/24/13 2:21 PM
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.

For more options, visit https://groups.google.com/groups/opt_out.
 
 

unk...@googlegroups.com 7/25/13 8:25 AM <This message has been deleted.>
Re: [AngularJS] Re: documentation generator Lior M 7/25/13 9:02 AM
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 
Re: [AngularJS] Re: documentation generator John Martin 7/25/13 11:19 AM
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:

John
Re: [AngularJS] Re: documentation generator Lior M 7/25/13 2:06 PM
thanks John, will do
Re: documentation generator Andrew Joslin 7/25/13 3:10 PM
@John, what do you think of grunt-ngdocs? https://github.com/m7r/grunt-ngdocs

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