angular
Document the tool!!
The project should be eating its own dog food by generating its own docs. This will be a good exercise in the versatility of the tool, since there are some project specific concepts such as packages and processors that would have their own doctypes.
Anyone want to have a go at creating a bike-shed package?
I am thinking we could start with writing some documentation in the comments for each of the processors. Fancy that?
@petebacondarwin I've played around with the tool for quite some time and think it is pretty promising, but i don't think i will have enough time to make a deep impact here in the near future. But one thing I'm currently working on is a 'guide' of migrating a docular based documentation to bike-shed. I've already ported some existing documentation and the migration effort was quite low.
That is fantastic! Can you publish your guide? We could add it to the docs for dgeni (a.k.a. bike-shed).
On 11 February 2014 07:46, johann-sonntagbauer [email protected]:
@petebacondarwin https://github.com/petebacondarwin I've played around with the tool for quite some time and think it is pretty promising, but i don't think i will have enough time to make a deep impact here in the near future. But one thing I'm currently working on is a 'guide' of migrating a docular based documentation to bike-shed. I've already ported some existing documentation and the migration effort was quite low.
Reply to this email directly or view it on GitHubhttps://github.com/angular/bike-shed/issues/18#issuecomment-34732538 .
yes i can, i will polish it a little bit and formulate it as an pull request at the weekend. is that in your intention?
Perfect!
On 11 February 2014 07:52, johann-sonntagbauer [email protected]:
yes i can, i will polish it a little bit and formulate it as an pull request at the weekend. is that in your intention?
Reply to this email directly or view it on GitHubhttps://github.com/angular/bike-shed/issues/18#issuecomment-34732748 .
@johann-sonntagbauer any luck with that guide? Even if it's not done I'd like to look at what it is so far, and could finish polishing it if you didn't have time to.
Hi @ajoslin. I would love to do two things. Document the tool and create a demo of how the the tool works. Do you fancy working with me on creating both? If we could get the basic structure working others could fill in the gaps
Hey!
I've been trying to figure out how dgeni works for some time, and the amount of needed configuration that is barely documented is.. quite a lot. But hence its open source, I could offer you to try to help to figure it out and how to make an easy way for a custom config that works. It's basicly what I need to do anyways, but I could really use some information.
@johann-sonntagbauer created a dgeniseed repository, which is empty for now, unfortunately. But it would be ideally something anyone could you for documenting angular modules and not writing their own doc pages.
And yes, you are absolutely right, dgeni should be dog food for itself and it should be able to generate its documentary.
Excellent! Let's get started. First we need some Pull Requests with jsdoc tagged comments on the code that is in dgeni and dgeni-packages. Anyone fancy having a go over the weekend?
On 27 February 2014 16:43, Alexander Plavinski [email protected]:
Hey!
I've been trying to figure out how dgeni works for some time, and the amount of needed configuration that is barely documented is.. quite a lot. But hence its open source, I could offer you to try to help to figure it out and how to make an easy way for a custom config that works. It's basicly what I need to do anyways, but I could really use some information.
@johann-sonntagbauer https://github.com/johann-sonntagbauer created a dgeniseed https://github.com/johann-sonntagbauer/dgeniseed repository, which is empty for now, unfortunately. But it would be ideally something anyone could you for documenting angular modules and not writing their own doc pages.
And yes, you are absolutely right, dgeni should be dog food for itself and it should be able to generate its documentary.
Reply to this email directly or view it on GitHubhttps://github.com/angular/dgeni/issues/18#issuecomment-36262277 .
Hi, sorry had to shift priorities for now. I'm perfectly fine if someone else takes that part. I will help out when I have some time left.
No problem. We'll still be here when you have a little more time. Thanks for showing an interest in Dgeni On 27 Feb 2014 17:24, "Johann Hubert Sonntagbauer" [email protected] wrote:
Hi, sorry had to shift priorities for now. I'm perfectly fine if someone else takes that part. I will help out when I have some time left.
Reply to this email directly or view it on GitHubhttps://github.com/angular/dgeni/issues/18#issuecomment-36267050 .
I'd like to suggest some documentation tags specific to dgeni.
doc-processors
/**
* @dgeni processor
* @name api-docs
* @config
* - (get) {string} rendering.contentsFolder desc
* - (get) {object} [processing.api-docs={}] desc
* @runsAfter
* - compute-id
* - partial-names
* @runsBefore
* - compute-path
* @exports
* - {object} moduleMap
* @description
* Computes the various fields for docs in the API area
*/
I think the multiple config list would probably be just multiple config tags. (Likewise with runsAfter, runsBefore and exports)
/**
* @runsAfter compute-id
* @runsAfter partial-names
*/
Not sure how set and merge document.... I think trying to express configuration setup and output in the code and documentation is pretty vital to understand what's going on - just trying to spark some discussion. I'll have some more insights a bit later when I have a bit more time.
@johann-sonntagbauer have you made any local progress with dgeniseed?
For Dgeni I was wondering whether we could just parse this info directly from the code? On 18 May 2014 07:01, "Nate-Wilkins" [email protected] wrote:
I'd like to suggest some documentation tags specific to dgeni.
doc-processors
/** * @dgeni processor * @name api-docs * @config * - (get) {string} rendering.contentsFolder desc * - (get) {object} [processing.api-docs={}] desc * @runsAfter * - compute-id * - partial-names * @runsBefore * - compute-path * @exports * - {object} moduleMap * @description * Computes the various fields for docs in the API area */
I think the multiple config list would probably be just multiple configtags. (Likewise with runsAfter, runsBefore and exports)
/** * @runsAfter compute-id * @runsAfter partial-names */
Not sure how set and merge document.... I think trying to express configuration setup and output in the code and documentation is pretty vital to understand what's going on - just trying to spark some discussion. I'll have some more insights a bit later when I have a bit more time.
@johann-sonntagbauer https://github.com/johann-sonntagbauer have you made any local progress with dgeniseedhttps://github.com/johann-sonntagbauer/dgeniseed ?
— Reply to this email directly or view it on GitHubhttps://github.com/angular/dgeni/issues/18#issuecomment-43432266 .
From like esprima? Would definitely remove a lot of repetition and synchronization! Sounds good if @johann-sonntagbauer is busy I can start setting up a framework.
Did you see that we have the AST from esprima already thanks to the latest jsdoc doc reader:
https://github.com/angular/dgeni-packages/blob/master/jsdoc/file-readers/jsdoc.js
This adds a codeNode property to the docs that it reads.
+1, please!
I would document it, but catch 22: I can't document it if I don't know how to use it (or don't spend a copious amount of time banging my head against the wall), which documentation would provide!
This tool is complex and not self explanatory. It's powerful though, and many more people would use it if there was just more documentation.
On the other hand, it is hilarious and way too ironic how a documentation tool is undocumented, so perhaps it should stay that way, hehe.
On the other hand, it is hilarious and way too ironic how a documentation tool is undocumented
Yes it is :D
so perhaps it should stay that way, hehe.
No :(
@aeharding I started working on a dgeni processor much like the one in the branch docs-docs under docs/processors but wanted to wait for any changes that came out of the new-config and no-config branches.
@petebacondarwin Could we merge (and possibly remove) some of these branches? In the meantime though I could fill in some of the blank docs under the english guide if those haven't been started - simple example / using dgeni and possibly some of the architecture docs.
@Nate-Wilkins - I want to move master to this branch: https://github.com/angular/dgeni/tree/no-config. This branch is solid but such a big breaking change that dgeni-packages, dgeni-example and angular.js need lots of work to make them compatible. I am working on this but only in dribs and drabs between other things. I hope to have it done by the end of this week.
@petebacondarwin Cool I'll make sure the docs reflect the changes in the no-config branch then check up on some older docs that might be out of date.
BTW I also would like to move to the new angular di.js project for dependency injection which would change things a bit again.
Hi @petebacondarwin, hi @Nate-Wilkins,
I also would like to help you. However, would it not be possible to create a roadmap and cut it into several pieces. Today, it is difficult to help you because each new commit to new ideas appear. And therefore it is very difficult to help you as the update dgeni-package. I am aware of the work that you provide on other project and would be happy if we could help you in this direction. What do you think?
@forresst +1 That would be awesome. That way we could plan out a little better what everyone's working on and where it's going.
The main feature of dgeni is to convert source code to some kind of document file. This could be a full HTML page, a partial HTML page, a markdown encoded text file or something else. Dgeni does not provide the wrapper web application to display these output files. That is up to the individual developer. That being said the long term aim is to provide a kind of container web app that could accept a standardized set of files output from dgeni.
There are a few examples of people's own implementation of a web app around dgeni generated files. The most comprehensive is the AngularJS documentation app which is hosted at docs.angularjs.org - the source code is at https://github.com/angular/angular.js/tree/master/docs
On 12 July 2014 23:13, Liviu [email protected] wrote:
Is there an example of using dgeni to generate documentation that's viewable in a browser? similar to how docular does it? right now I can only get it to generate simple html files. Is dgeni supposed to be used by some higher level documentation generator/assembler/viewer?
— Reply to this email directly or view it on GitHub https://github.com/angular/dgeni/issues/18#issuecomment-48825500.