proposal: doc generation

[revolunet]

Basically, for each module, the doc structure could be a single-page with :

for README.md :

• include: 'docs/header.md'
• add repo info (from package.json)
• add bower dependencies (from bower.json)
• add badges (travis, coderwall, browserling...) : http://shields.io/
• for each docs/examples/example :
  • include: example.md
  • generate link to the live example (plnkr?)
• add ngdocs API
• add licence

for the gh-pages index.html : the same but with also :

• a nice CSS and embedded examples (Maybe the user can choose of the many bootswatch free themes? )
• examples source view.
• social badges

[mgcrea]

Pour info j'ai switch le ui-slider pour le composant alert d'AngularStrap, ça permet d'avoir du contenu direct pour dev ngFactory, avec les tests, etc.

Dans l'idée je pense dans un premier temps faire marcher la génération de template jade/html pour alimenter la demo, puis voir pour le markdown dans un second temps, je trouve ça bien d'avoir le choix, et c'est plus simple pour avancer car la construction du workflow est déjà un bon casse-tête.

[revolunet]

yo :) c'est quoi ton idée pour la "demo" ? tu parles pour la page de doc avec les embedded examples ?

[revolunet]

bon je te laisse avancer un peu sur la "doc" et je reviendrai sur le readme ensuite paske ca marche plus :)

[mgcrea]

Petite update, après être parti sur une solution custom pour la doc via le transform template, je suis tombé sur dgeni qui est un projet Angular spécifiquement monté pour ça. Du coup je suis entrain de regarder comment cela peut fonctionner dans notre cas... Je suis en vacs et très peu sur l'ordi donc je ne sais pas trop quand je vais pouvoir boucler ce point, mais je le garde en tête ;-). cc @douglasduteil @revolunet

[douglasduteil]

Haha c'est marrant on en parlait hier soir avec @revolunet . Je viens juste de finir d'isoler le parcer jsdoc de dgeni => ngDocParser C'est encore une phase alpha (il y a pas tous les tag jsdoc) mais ça rocks déjà pour le tag @param => DEMO

[mgcrea]

@douglasduteil Magique! Après avoir un peu regardé, dgeni me semble bien trop compliqué, et limite "over-engineered". Je rageais de ne pas trouver dans leur dépendance un parser de ngDoc indépendant pour refaire un truc très simple dessus. Bien joué. Je pense par contre switcher de lodash.template vers nunjuncks (utilisé par dgeni), ça devrait permettre des trucs sympa pour l'overriding de styles, etc.

[douglasduteil]

:+1:

[douglasduteil]

@mgcrea N'hésite pas a pusher ta branche WIP ça nous permettra de savoir où tu en es et d'avancer sur le même sujet aussi.

[mgcrea]

Pas trop le temps de faire de l'ordi, je suis encore en vac, ma branche WIP a pas grand chose en plus, j'avais surtout testé dgeni.

L'idée est que je trouve que ça serait idéal d'avoir à la fois la possibilité d'utiliser du markdown -> html ou de l'html/jade directement. Pour l'instant j'ai utilisé glob.sync dans la config pour récupérer les différents fichiers. L'idée est de loop dessus dans les templates nunjucks des docs.

Sinon dans le cas du module alert ou plus généralement dans AngularStrap, les paramètres du service sont représentés dans le code source dans le bloc defaults, qui a la syntaxe ngdocs suivante (prise de $http):

  /**
   * @ngdoc property
   * @name $alertProvider#defaults
   * @description
   *
   * Object containing default values for all {@link ng.$http $http} requests.
   *
   * - **`defaults.animation`** - {string} - Class to be added for animation purposes
   * Defaults value is `'am-fade'`.
   *
   * - **`defaults.prefixClass`** - {string} - Prefix prepended to class names and events
   * Defaults value is `'alert'`.
   *
   * - **`defaults.placement`** - {string} - Name of HTTP header to populate with the
   * XSRF token. Defaults value is `'X-XSRF-TOKEN'`.
   *
   * - **`defaults.placement`** - {string} - Name of HTTP header to populate with the
   * XSRF token. Defaults value is `'X-XSRF-TOKEN'`.
   *
   * - **`defaults.headers`** - {Object} - Default headers for all $http requests.
   * Refer to {@link ng.$http#setting-http-headers $http} for documentation on
   * setting default headers.
   *     - **`defaults.headers.common`**
   *     - **`defaults.headers.post`**
   *     - **`defaults.headers.put`**
   *     - **`defaults.headers.patch`**
   **/

ngDoc ne parse pas correctement le bloc, et sa structure ne permettrait pas un extract propre des champs. Donc faut voir si on suit le coeur sur ces guidelines ou si on utilise des blocs @param en attendant de trouver mieux.

Je vais voir si je peux pas avancer ça d'ici demain.

[douglasduteil]

C'est pas une histoire de jsdoc ? tu peux pas utiliser le tag @property http://usejsdoc.org/tags-property.html ?

/**
 * @ngdoc property
 * @name $alertProvider#defaults
 * @description
 *   Object containing default values for all {@link ng.$http $http} requests. 
 * @property {string} animation Class to be added for animation purposes
 * Defaults value is `'am-fade'`.
 * @property {string} prefixClass Prefix prepended to class names and events
 * Defaults value is `'alert'`.
 * @property {string} placement Name of HTTP header to populate with the
 * XSRF token. Defaults value is `'X-XSRF-TOKEN'`.
 */

http://usejsdoc.org/tags-typedef.html

[douglasduteil]

@mgcrea

L'idée est que je trouve que ça serait idéal d'avoir à la fois la possibilité d'utiliser du markdown -> html ou de l'html/jade directement.

Je suppose que l'on peux aussi utiliser nunjuncks comme moteur de doc par défaut vue qu'il fait le taff . Pour moi jade serait optionnel

[revolunet]

ha mais en fait nunjucks c'est des templates django-like, yuhu

[douglasduteil]

:+1:

[mgcrea]

@douglasduteil, OK pour le @property, par contre faut que tu patches ton parser pour le prendre en compte, a priori y'a pas non plus le support du multi-line ni des defaults.

On a donc quelque chose comme ça pour le moment:

  /**
   * @ngdoc property
   * @name $alertProvider#defaults
   * @description
   *   Object containing default values for all {@link mgcrea.ngStrap.alert $alert} objects.
   * @property {string} animation - Class to be added for animation purposes
   *   Defaults value is `'am-fade'`.
   * @property {string} prefixClass - Prefix prepended to class names and events
   *   Defaults value is `'alert'`.
   * @property {string} placement - How to position the alert
   *   Defaults value is `''`.
   **/

[douglasduteil]

@mgcrea

faut que tu patches ton parser

Ouaip D'ailleurs on peut inline la valeur par défaut en jsdoc

  /**
   * @ngdoc property
   * @name $alertProvider#defaults
   * @description
   *   Object containing default values for all {@link mgcrea.ngStrap.alert $alert} objects.
   * @property {string} [animation='am-fade'] - Class to be added for animation 
   * @property {string} [prefixClass='alert'] - Prefix prepended to class names and 
   * @property {string} [placement=''] - How to position the 
   **/

[mgcrea]

@douglasduteil top pour les defaults en inline, pour le multiline, ça presse pas du coup.

[douglasduteil]

Yo @mgcrea ngdoc-parser update 0.0.2 (new demo)

[douglasduteil]

Possible enhancement :

• getting a faster template processor https://github.com/kissyteam/xtemplate

[douglasduteil]

News from the factory.

First of all sry for not giving news on Sunday...

Code, Y U NO WORK ?

The pages generation things it's harder that I thought LOL. I pass a moment trying to get it working and I end up like : "Wat ? All those lines for this ?!". I'm now convinced that the design have to leave to a external module with some kind of common build/generate task/function that handle the mandatory generation.

Delete all the code

Yeah let's clean all this mess ! The npm install of this "design" module will trigger the bower install of it.

// in the package.json
"scripts" : {
  "postinstall" : "bower install"
}

The page processing will be in three steps:

1. Coping to tmp
   • copy the origin design files
   • copy the user changed files
2. Generate to out
   • Generate all the pages from the tmp to out with the used theme build routine. Use a common notation like : build(from, to, callback)
   • Watch for changes too.
3. Watch the output files
   • Output all the files at the same location (emulation the final gh-pages branch result)
   • Watch, live reload and debounce changed there.

Communication between the theme and the ng-factory

I'm still not sure of how to do it "the right way". I thing that sticking with the basic "file replacement if excits" is not a bad solution. So you can overwrite any files of the theme.

For me all the files in .ng-factory/pages will overwrite the original files in the .tmp/pages.

If you need more you might just add and compile stuff from .ng-factory/pages -> .tmp/pages -> out/pages (for example)

I still don't know how it'll work. I need to try it to see if it's cool or not.

---