New Functionality.

[robblovell]

I hesitate to propose this pull request, but here it goes anyway. If you want to keep what you have, as is, I am happy to start down a new path and reference and be referenced by your work with docco. That said I am really happy if you decide the changes are valuable and incorporate them.

Added Functionality:

• Added configuration file capabilities with a .docco.json file
• --setup flag to specify a different configuration file
• Images (.png, .jpg, .jpeg and .tiff) can now be copied to the documentation directory
• The source directory structure is kept in the target location by default
• --flatten flag to override keeping the directory structure and flattening it
• For markdown files, referenced images are displayed in the code section
  which means that in the parallel theme, images are displayed on the right
• Multiline comments
• Allow images to be removed from the link menu for templates
• New layout: sidebyside

Refactors:

• Code refactored into smaller chunks
• Unit testing framework added and unit tests written to %85 coverage (more work needed here)
• 'npm build' builds all javascript with gulp
• 'npm test' runs all unit tests
• travis ci build and badge

Possible Breaking Changes:

• .jst template files have a different set of data available for building links to other files.
  The question here is are there other templates that have been created and should a backward compatibility flag be added to proved the old behaviour?

This:
<a class="source" href="<%= path.basename(destination(source)) %>">

Can be changed to whatever is needed since links to all other files as well as other options are available:

             <% for (var i=0, l = links.length; i < l; i++) { %>
                <li>
                  <a class="source" href="<%= links[i].link %>">
                    <% if (flatten) %>
                    <%= path.basename(links[i].file) %>
                    <% else %>
                    <%= links[i].file %>
                  </a>
                </li>
              <% } %>

• hierarchical directory structure of source is kept by default.
  Use --flatten to get the old behaviour
  Should this flag be changed to something else with a default behaviour being flatten?

Anyway, that's a lot of features and changes.

[jashkenas]

Holy crap!

Do you have a link to an example of your new sidebyside layout?

[robblovell]

Here's an example: https://builddirect.github.io/deals-service/

It's very similar to the parallel layout, there are just changes to the menu structure right now. The intent was to have a three column format, but I don't have enough css mojo to be able to pull it off. So instead i just went with annotating the directory associated with the files in the dropdown menu.

[jashkenas]

Can you talk a little about how you're supporting multiline comments? What did you have to change?

[robblovell]

To support multiline comments I added to the language.jason:

"multiline": {"start": "/*", "stop": "*/"}}
or
"multiline": {"start": "###", "stop": "###"}

The parser code uses this to find the markers in the code. Since it goes line by line, the assumption is that when the marker is found, a flag is on to redirect the next lines to the docsText section until the stop marker is found.

The manipulation of hasCode parallels the behaviour of normal docText, except the final save is not done, and there needs to be a switch back to the code finding with hasCode set to yes at the end. The assumption is that the parser is in a code section, so it needs to go back to code mode.