# `Documentation Section`

- ### section {object}

  Sections are objects that create logical sections for documentation generation withing a group.

  #### Properties

  - `id` – `{string}` –

    The unique id that is used internally and appears within the url for each doc parsed

  - `title` – `{string}` –

    The title of the section that is used often in the UI

  - `showSource` – `{boolean}` –

    Defaults to false. When true will copy all source files to the webapp so they can be displayed in the UI. WARNING All files within this section should be considered public. All information should be considered insecure. Note, this section level 'showSource' configuration will override the group level setting.

  - `scripts` – `{array : paths}` –

    An array of paths that may reference a directory or a single file. The single file or every file in the directory will be scanned for documentation THAT IS WITHIN BLOCK COMMENTS.

    Currently, scripts need to end in ".js". This will change in the future to allow any type of script.

        /**
         * @doc docType
         * @doc id
         * @doc name
         * @doc description
        */

  - `docs` – `{array : paths}` –

    An array of paths that may reference a directory or a single file. The single file or every file in the directory will be scanned for documentation THAT IS NOT WITHIN COMMENTS.

    Doc files must have an extension of ".doc" or ".ngdoc".

        @doc docType
        @doc id
        @doc name
        @doc description

  - `rank` – `{object}` –

    The rank object contains key value pairs, where the key is an id of a document and the value is the ranking associated with that document. This object is used to place sections in order within the UI. If a document does not have a rank, it is automatically set to a large number (which pushes it to the bottom).

## Sample section object

Below we have included ONE of the sections normally added for the default Docular documenation

    module.exports = function(grunt) {

        // Project configuration
        grunt.initConfig({

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

            docular: {
                groups: [
                    {
                        groupTitle: 'Docular',
                        groupId: 'docular',
                        groupIcon: 'icon-beer',
                        sections: [
                            {
                                id: "docularinstall",
                                title: "Install Docular",
                                showSource: false,
                                docs: [
                                    "lib/scripts/docs/install"
                                ],
                                rank: {
                                    'installnode':1,
                                    'installgrunt':2,
                                    'installdocular':3
                                }
                            },
                            //the rest of the section objects ommitted
                        ]
                    }
                ],
                //other configurations ommitted here for simplicity
            }

        });

        // Load the plugin that provides the "docular" tasks.
        grunt.loadNpmTasks('grunt-docular');

        // Default task(s).
        grunt.registerTask('default', ['docular']);

    };

## The difference between Docs and Scripts

We provide two buckets, "docs", and "scripts" as configurations within a section object. You can certainly use both within one section but understanding the difference is important.

Every directory or filename specified within the "docs" array will be parsed for documentation that exists NOT within comments in that file. So "docs" files are meant to basically be non-code files with "overview" or "tutorial" type information. Doc files are there for providing a more convient way of creating documentation that doesn't necessarily depend on actual code.

As of this writing, all "doc" files should have a ".doc" or ".ngdoc" extension.

If you specify a file or directory within the "scripts" array, those files will all be scanned for documentation WITHIN block comments. This is a great way to add documentation inline and near your actual code.

There is a lot of flexibility so just follow what works for your project.

## Group Configuration for Docular

    {
        groupTitle: 'Docular',
        groupId: 'docular',
        groupIcon: 'icon-edit',
        descr: 'Description',
        showSource: true,
        sections: [
            {
                id: "docularinstall",
                title: "Install Docular",
                docs: [
                    "lib/scripts/docs/install"
                ],
                rank: {
                    'installnode':1,
                    'installgrunt':2,
                    'installdocular':3
                }
            },
            {
                id: "docularconfigure",
                title: "Docular Configurations",
                docs: [
                    "lib/scripts/docs/configure"
                ],
                rank: {
                    'show':1,
                    'groups':2,
                    'sections':3,
                    'discussions':4,
                    'analytics':5,
                    'partials':6,
                    'ui':7
                }
            },
            {
                id: "docularcreate",
                title: "Documentation Groups and Sections",
                docs: [
                    "lib/scripts/docs/create"
                ],
                rank: {'configuregroup':1, 'configuresection':2, 'firstdoc':3}
            },
            {
                id: "embed",
                title: "Embedding Documentation",
                docs: [
                    "lib/scripts/docs/embed"
                ],
                rank: {'blockdef_js':1, 'blockdef_doc':2}
            },
            {
                id: 'basics',
                title: 'Documentation Basics',
                docs: [
                    "lib/scripts/docs/basics"
                ],
                rank : {
                    'identifier':1,
                    'naming':2,
                    'fields':3,
                    'modules':4,
                    'sections':5,
                    'types':6,
                    'types_doc':7,
                    'types_ngdoc':8,
                    'children':9,
                    'links':10
                }
            },
            {
                id: "doctypes",
                title: 'Documentation Types (DocTypes)',
                docs: [
                    "lib/scripts/docs/doctypes/doctypes.doc"
                ],
                rank : {'types_doc':2, 'types_ngdoc':3}
            },
            {
                id: "docularext",
                title:"Docular Extensions",
                scripts: [],
                docs: [
                    "lib/scripts/docs/extensions"
                ]
            },
            {
                id: "docular",
                title:"Docular Source",
                scripts: [
                    "lib/scripts/gen-docs.js",
                    "lib/scripts/reader.js",
                    "lib/scripts/writer.js",
                    "lib/scripts/Doc.js"
                ],
                docs : [
                    "lib/scripts/docs/node",
                    "README.md"
                ]
            },
            {
                id: "docularfaq",
                title:"FAQs",
                scripts: [],
                docs: [
                    "lib/scripts/docs/faq"
                ]
            }
        ]
    }

## Group Configuration for AngularJS Source

We made some small tweaks, but ported over most of the AngularJS "scripts" and "docs" in tact.

    {
        groupTitle: 'Angular',
        groupId: 'angular',
        groupIcon: 'icon-book',
        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"]
            }
        ]
    }