diff --git a/README.md b/README.md index c14ef13..8507f87 100755 --- a/README.md +++ b/README.md @@ -4,14 +4,14 @@ [![NPM version](https://badge.fury.io/js/docular.svg)](http://badge.fury.io/js/docular) -#New Beta Version +# New Beta Version Version 0.8.x is out. The API at this point should be considered stable. -#Docular +# Docular Extensible Documentation Generation Based on AngularJS's Documentation Generation -#Grunt Plugin For Docular: "grunt-docular" +# Grunt Plugin For Docular: "grunt-docular" Docular is best used as a dependency by the grunt-docular plugin. The grunt-docular plugin exposes the api in a simple fashion and helps you include documentation tasks in your grunt-based build process. diff --git a/docs/configuration/index.md b/docs/configuration/index.md index 3b23b51..e76bac5 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -1,4 +1,4 @@ -#Configuration +# Configuration Docular has a small set of configuration options that you should be familiar with. When you configure docular, you are actually configuring the base 'group'. Each 'group' accepts the same parameters, but some are only respected @@ -8,7 +8,7 @@ Docular is also split up into plugins. The primary codebase is responsible for s All plugin parameters are part of the group object, unless otherwise specified. -##Docular parameters +## Docular parameters Required parameters are in **bold**. @@ -32,7 +32,7 @@ Required parameters are in **bold**. | showDocularDocs | ```false``` | Should Docular docs be included in the output? If so, they will be listed under a 'Docular' tab. | | useHtml5Mode | ```false``` | Whether or not to use Angular's HTML5 mode. If you use this mode, you must have the proper hosting setup to serve html5 mode pages. Docular's grunt task comes with a simple server that will do this for you, but should not be considered production-ready.| -##docular-ng-plugin parameters. +## docular-ng-plugin parameters. Required parameters are in **bold**. @@ -45,7 +45,7 @@ Required parameters are in **bold**. | examples.include.js | ```empty array``` | An array of javascript files that should be included in the examples. This is relative to the root of the docular application. For example, ```['./doc_files/start.js']```. This will cause the examples to load a file called ```start.js```.| | examples.include.css | ```empty array``` | Basically the exact same thing as ```examples.include.js```, except is meant for CSS files | -##Notes on backwards compatibility with 0.6.x +## Notes on backwards compatibility with 0.6.x * The section key is read in as a group key. * The scripts and docs keys are read in and appended to the files key. diff --git a/docs/index.md b/docs/index.md index eead34b..fe93a83 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1 +1 @@ -#Docular docs +# Docular docs diff --git a/docs/installation/index.md b/docs/installation/index.md index c8b829a..6fd5052 100755 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -1,153 +1,153 @@ -#Installation - -Installing docular is fairly straightforward. The most likely way you will use docular is through its -[grunt-docular](https://github.com/Vertafore/grunt-docular) -plugin. There are few prerequisites that you must manually take care of. - -1. You need [Node.js](http://nodejs.org) installed. -2. You need [Grunt](http://www.gruntjs.com) installed. -3. You need to setup your package.json file. -4. You need to setup your Gruntfile.js file. - -##Installing Node - -For most systems, installing Node is straightforward. For Windows and Mac, there are prebuilt installers available -on the Node.js [download page](http://nodejs.org/download/). Most linux systems will install Node through their own -package system, though some do not bundle NPM (Node Package Manager) with the Node application. For instance, in Ubuntu -you need to run ```sudo apt-get install nodejs``` and then ```sudo apt-get install npm```. - -##Installing Grunt - -In order to run Grunt via the command line, as you'll have to do in order to run the grunt-docular task, you will need -to install the [grunt-cli](https://www.npmjs.org/package/grunt-cli) package. Since it's an executable, you need to -install it with NPM globally. This is done by running ```npm install -g grunt-cli```. - -##Setting up your package.json file - -Current docular versions: -* docular: [![NPM version](https://badge.fury.io/js/docular.svg)](http://badge.fury.io/js/docular) -* grunt-docular: [![NPM version](https://badge.fury.io/js/grunt-docular.svg)](http://badge.fury.io/js/grunt-docular) - -If you aren't familiar with what a package.json file is, you should probably [read through the docs](https://www.npmjs.org/doc/files/package.json.html). -The shorter version is that you will want a file setup like this: - -```js - { - "name": "YourProjectName", - "version": "0.0.1", - "devDependencies": { - - } - } -``` - -The ```devDependencies``` key is the important one to note. Normally you'd add your dependencies in via the ```dependencies``` -key. However, grunt-docular isn't something that your application requires to run. It is only necessary as a tool for -development, hence the ```devDependencies```. - -Inside of ```devDependencies```, add ```"grunt": "~0.4.0"``` and ```"grunt-docular": "~TheVersionAbove"```. In case you -aren't familiar, the tilde tells NPM to install a version that is "reasonably close" to the specified version. This -will ensure you get bugfixes, but shouldn't cause you to switch to minor or major releases. - -After you have those two items added to ```devDependencies```, run ```npm install```. This will spider through all of the -dependencies and install them. - -##Setting up your Gruntfile.js - -Specific configuration parameters can be found in the @{link configuration/index configuration docs}. - -Setting up your Gruntfile.js to look like the following: - -```js - -module.exports = function (grunt) { - grunt.initConfig({ - docular: { - //We'll fill in this in a minute - } - }); - - grunt.loadNpmTasks('grunt-docular'); - -} - -``` - -Now that you've got that, we need to give Docular instructions on how to generate its files. First, let's tell it -where to put the generated files by setting the ```docular_webapp_target``` directory to ```docs```. Then, lets have -it show the angular docs by default by adding in the key ```showAngularDocs``` with the value of ```true```. Finally, -we want to give the site a title. Set the ```groupTitle``` key to the name of your site - for example "My Docs". - -Now, run ```grunt docular```. You should see some text fly by as Angular gets downloaded, parsed, and then generated -into documentation. This is great, but you need to actually be able to see it. - -There are a couple options here. - -###Using grunt-docular's builtin server. -One of Docular's contributors added a small webserver to it called 'docularserver'. To make that work, -add the follwoing to your initConfig object: - -```js -docularserver: { - targetDir: 'docs', - port: 8888 -} -``` - -Then run ```grunt docularserver```. Voila - your documentation has been served. - -###Using a third party server - -You could serve these files up with something like Apache.. or you can try serving them with another Grunt task. - -One of the grunt file servers out there is called 'devserver'. To install, you add ```"devserver": "*"``` to your -```devDependencies```, run ```npm install``` again, and add the following to your initConfig object: - -```js -devserver: { - docs: { - options: { - base: './docs', - port: 8888 - } - } -} -``` -This will allow you to run ```grunt devserver:docs```, which will serve up all the files on the machine's IP address -and specified port. For example, [http://localhost:8888](http://localhost:8888). - -##Documentation generation for your code - -In the ```docular``` section of the config, add a ```groups``` array. Inside of that array, we need a minimum of: - -* groupTitle - the title of this section of documentation... such as "Site Controls" -* groupId - the ID that is to be used to keep groups organized and make it easier to find code that relates to one another. -For example, 'siteControls'. -* files - a list of files that need to be parsed. The best way of providing this is by using ```grunt.file.expand```, -which accepts a series of file filters. - -For example: - -```js - -module.exports = function (grunt) { - grunt.initConfig({ - docular: { - groupTitle: 'My documentation site', - groups: [ - { - groupTitle: 'Site Controls', - groupId: 'siteControls', - files: grunt.file.expand(['public/javascript/**/*.js']) - } - ] - } - }); - - grunt.loadNpmTasks('grunt-docular'); - -} - -``` - +# Installation + +Installing docular is fairly straightforward. The most likely way you will use docular is through its +[grunt-docular](https://github.com/Vertafore/grunt-docular) +plugin. There are few prerequisites that you must manually take care of. + +1. You need [Node.js](http://nodejs.org) installed. +2. You need [Grunt](http://www.gruntjs.com) installed. +3. You need to setup your package.json file. +4. You need to setup your Gruntfile.js file. + +## Installing Node + +For most systems, installing Node is straightforward. For Windows and Mac, there are prebuilt installers available +on the Node.js [download page](http://nodejs.org/download/). Most linux systems will install Node through their own +package system, though some do not bundle NPM (Node Package Manager) with the Node application. For instance, in Ubuntu +you need to run ```sudo apt-get install nodejs``` and then ```sudo apt-get install npm```. + +## Installing Grunt + +In order to run Grunt via the command line, as you'll have to do in order to run the grunt-docular task, you will need +to install the [grunt-cli](https://www.npmjs.org/package/grunt-cli) package. Since it's an executable, you need to +install it with NPM globally. This is done by running ```npm install -g grunt-cli```. + +## Setting up your package.json file + +Current docular versions: +* docular: [![NPM version](https://badge.fury.io/js/docular.svg)](http://badge.fury.io/js/docular) +* grunt-docular: [![NPM version](https://badge.fury.io/js/grunt-docular.svg)](http://badge.fury.io/js/grunt-docular) + +If you aren't familiar with what a package.json file is, you should probably [read through the docs](https://www.npmjs.org/doc/files/package.json.html). +The shorter version is that you will want a file setup like this: + +```js + { + "name": "YourProjectName", + "version": "0.0.1", + "devDependencies": { + + } + } +``` + +The ```devDependencies``` key is the important one to note. Normally you'd add your dependencies in via the ```dependencies``` +key. However, grunt-docular isn't something that your application requires to run. It is only necessary as a tool for +development, hence the ```devDependencies```. + +Inside of ```devDependencies```, add ```"grunt": "~0.4.0"``` and ```"grunt-docular": "~TheVersionAbove"```. In case you +aren't familiar, the tilde tells NPM to install a version that is "reasonably close" to the specified version. This +will ensure you get bugfixes, but shouldn't cause you to switch to minor or major releases. + +After you have those two items added to ```devDependencies```, run ```npm install```. This will spider through all of the +dependencies and install them. + +## Setting up your Gruntfile.js + +Specific configuration parameters can be found in the @{link configuration/index configuration docs}. + +Setting up your Gruntfile.js to look like the following: + +```js + +module.exports = function (grunt) { + grunt.initConfig({ + docular: { + //We'll fill in this in a minute + } + }); + + grunt.loadNpmTasks('grunt-docular'); + +} + +``` + +Now that you've got that, we need to give Docular instructions on how to generate its files. First, let's tell it +where to put the generated files by setting the ```docular_webapp_target``` directory to ```docs```. Then, lets have +it show the angular docs by default by adding in the key ```showAngularDocs``` with the value of ```true```. Finally, +we want to give the site a title. Set the ```groupTitle``` key to the name of your site - for example "My Docs". + +Now, run ```grunt docular```. You should see some text fly by as Angular gets downloaded, parsed, and then generated +into documentation. This is great, but you need to actually be able to see it. + +There are a couple options here. + +### Using grunt-docular's builtin server. +One of Docular's contributors added a small webserver to it called 'docularserver'. To make that work, +add the follwoing to your initConfig object: + +```js +docularserver: { + targetDir: 'docs', + port: 8888 +} +``` + +Then run ```grunt docularserver```. Voila - your documentation has been served. + +### Using a third party server + +You could serve these files up with something like Apache.. or you can try serving them with another Grunt task. + +One of the grunt file servers out there is called 'devserver'. To install, you add ```"devserver": "*"``` to your +```devDependencies```, run ```npm install``` again, and add the following to your initConfig object: + +```js +devserver: { + docs: { + options: { + base: './docs', + port: 8888 + } + } +} +``` +This will allow you to run ```grunt devserver:docs```, which will serve up all the files on the machine's IP address +and specified port. For example, [http://localhost:8888](http://localhost:8888). + +## Documentation generation for your code + +In the ```docular``` section of the config, add a ```groups``` array. Inside of that array, we need a minimum of: + +* groupTitle - the title of this section of documentation... such as "Site Controls" +* groupId - the ID that is to be used to keep groups organized and make it easier to find code that relates to one another. +For example, 'siteControls'. +* files - a list of files that need to be parsed. The best way of providing this is by using ```grunt.file.expand```, +which accepts a series of file filters. + +For example: + +```js + +module.exports = function (grunt) { + grunt.initConfig({ + docular: { + groupTitle: 'My documentation site', + groups: [ + { + groupTitle: 'Site Controls', + groupId: 'siteControls', + files: grunt.file.expand(['public/javascript/**/*.js']) + } + ] + } + }); + + grunt.loadNpmTasks('grunt-docular'); + +} + +``` + Run ```grunt docular``` again, and you should see your documentation pop up on the site. \ No newline at end of file diff --git a/docs/plugins/index.md b/docs/plugins/index.md index ef3ac72..0f3394c 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -1,4 +1,4 @@ -#Docular plugins +# Docular plugins There are currently two officially available plugins for Docular. @@ -7,13 +7,13 @@ There are currently two officially available plugins for Docular. * [docular-markdown-plugin](https://github.com/Vertafore/docular-markdown-plugin) This plugin gives Docular the ability to create pages based off of simple markdown files. -##Creating a plugin +## Creating a plugin The plugin API has changed significantly since 0.6.x due to a strong desire to limit how much Docular has to call each plugin. Instead, it was desired that each plugin should listen for events emitted from Docular and respond appropriately. To create a plugin, you need to setup your project in such a way that Docular understands it. -###Your package.json +### Your package.json At minimum, you should specify what your main file is for your project. To do this, set the ```main``` key to your main file. For example: @@ -28,7 +28,7 @@ At minimum, you should specify what your main file is for your project. To do th Docular uses the ['q' library](https://github.com/kriskowal/q), so you should also use that or a library that is compatible with it. This is because certain events allow you to add promises to a shared array so that Docular will wait until your plugin is ready for the application to proceed. This can be seen in docular-ng-plugin, where the ProcessConfig event is called and it fetches Angular code for documenting if needed. -###Your main file +### Your main file Your main file needs to export a "new-able" function that has at least one method called "register". The "register" method will be provided the running instance of Docular, so that it may attach itself to events. Calling methods on the Docular instance is highly discouraged, as API changes may completely break your plugin. @@ -51,7 +51,7 @@ As an example, this is the register method from the docular-ng-plugin: ``` -###Events +### Events There are currently eight events that can be listened to. @@ -64,7 +64,7 @@ There are currently eight events that can be listened to. 7. GetStyles. This event is emitted with one parameter - an array which you can push [less](http://lesscss.org/) styles into which will be appended to the bottom of the Docular stylesheet. You should use this if you want to extend Docular or Bootstrap styles in your plugin. This may change in the future, as the current implementation feels a bit hacky. 8. CopyFiles. This event is emitted with one parameter - the folder where all of the generated files will be stored. You should use this event if you need to copy some of your own files. Use the 'sync' rather than 'async' functions here. Too many open files will cause the grunt process to crash, so it was decided that this would not be a promise setup. -###The document model +### The document model A document model is just an object that must have the following methods and properties exposed: diff --git a/docs/writing/index.md b/docs/writing/index.md index 3367f3a..91536cd 100644 --- a/docs/writing/index.md +++ b/docs/writing/index.md @@ -1,4 +1,4 @@ -#Writing documentation +# Writing documentation Docular's first and foremost goal is to stay in step with Angular's documentation practices. To that end, you should read their [documentation guide](https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation). @@ -113,7 +113,7 @@ Here are some examples of documentation, right from the Angular source: Anything in the @description is considered to be markdown syntax, and so you can use markdown for formatting, links, code snippets, etc. -##Extra parameters +## Extra parameters There are some parameters that I feel are missing from the angular documentation syntax, which are going to be added as time allows. diff --git a/lib/scripts/docs/basics/basics.md b/lib/scripts/docs/basics/basics.md index d0512f9..8253a9a 100644 --- a/lib/scripts/docs/basics/basics.md +++ b/lib/scripts/docs/basics/basics.md @@ -3,7 +3,7 @@ @name @description -#Documentation Basics +# Documentation Basics Check out the following links to understand the basic documentation syntax, naming conventions, and module management. @@ -215,7 +215,7 @@ Here is a markdown list In every case there is a key next to the "@" symbol and then the value is everything after the key until the next key is found, the code block ends, or the next {@link identifier documentation identifier} is encountered. Multiline is supported but is typically used most often for "@description" type keys. -#Standard Key Value Pairs +# Standard Key Value Pairs ## 1. @doc / @ngdoc - Documentation Identifier And Doctype diff --git a/lib/scripts/docs/configure/configure.md b/lib/scripts/docs/configure/configure.md index d018571..3f862ca 100644 --- a/lib/scripts/docs/configure/configure.md +++ b/lib/scripts/docs/configure/configure.md @@ -3,7 +3,7 @@ @name Configure Docular @description -#Docular Configurations +# Docular Configurations The links below illustrate the use of Docular configurations via the grunt-docular.com website. The links will take you through each of configurations listed at the bottom of this page in the example Gruntfile.js file. diff --git a/lib/scripts/docs/doctypes/doctypes.md b/lib/scripts/docs/doctypes/doctypes.md index 1ef6b40..e29307d 100644 --- a/lib/scripts/docs/doctypes/doctypes.md +++ b/lib/scripts/docs/doctypes/doctypes.md @@ -3,7 +3,7 @@ @name DocTypes Intro @description -#Documentation Types (DocTypes) +# Documentation Types (DocTypes) Things to know about ``docTypes``. diff --git a/lib/scripts/docs/embed/embed.md b/lib/scripts/docs/embed/embed.md index 6a73ae2..036491c 100644 --- a/lib/scripts/docs/embed/embed.md +++ b/lib/scripts/docs/embed/embed.md @@ -3,7 +3,7 @@ @name Embedding Documentation @description -#Embedding Documentation +# Embedding Documentation Follow this overview to familiarize yourself with the basics of embedding documentation within your script files and separate 'doc' files. diff --git a/lib/scripts/docs/install/install.md b/lib/scripts/docs/install/install.md index 666a4ff..5472576 100644 --- a/lib/scripts/docs/install/install.md +++ b/lib/scripts/docs/install/install.md @@ -1,7 +1,7 @@ @doc overview @name index @description -#Installing Docular +# Installing Docular Installing Docular is as simple as adding the grunt-docular Grunt plugin to your project, customizing the Docular configurations, and then simply authoring your own documentation. diff --git a/lib/scripts/docs/sublime/sublime.md b/lib/scripts/docs/sublime/sublime.md index deedb7e..7a3403a 100644 --- a/lib/scripts/docs/sublime/sublime.md +++ b/lib/scripts/docs/sublime/sublime.md @@ -1,7 +1,7 @@ @doc overview @name index @description -#Sublime Text Support +# Sublime Text Support So putting inline documentation within your script files can get a little unruly. Your script files should be fairly small to begin with, but sometimes the documentation that is displayed to those interested in learning your software can burden those looking at the code on a day to day basis. @@ -27,13 +27,13 @@ So putting inline documentation within your script files can get a little unruly When these conventions are followed, you can then hide all comment blocks and keep all single line comments visible during development! -##Sublime Time +## Sublime Time We have written a simple Sublime Text plugin to help with this process. The plugin uses the native "fold" functionality in the Sublime Text API to toggle the visibility of comment blocks. Once you add the plugin and add the key bindings, you can quickly toggle the visibility of comment blocks so you can focus on improving code or toggle again to focus on improving documentation. Keen! -##Sublime Plugin Installation +## Sublime Plugin Installation Follow this links to get the Docular Sublime Text plugin installed