Support for themes and redesign the .pyccoon file

[cryptonomicon314]

In my pull request we discussed possible mechanisms for theaming, including a linear theme like the one in Docco. I think it is agreat idea, but adapting the current .pyccoon file to handle themes is inconvenient.

I'd like to suggest a non-backward compatible change to the .pyccoon file that would make its structure much clearer and suport themes in an understandable way.

First, the file should be YAML instead of JSON, which can be parsed with PyYAML into a dict and has the advantage of being clearer (especially for nested items) and allowing comments. The structure I propose is the following:

# Items related to the project
#  (currently only the "name")
# Something useful we could add 
# (by changing the template) would be
# banners for "fork me on github" or
# "fork me on bitbucket", or a custom
# piece of HTML.
project:
    name: pyccoon v0.1.4 documentation
    banner: fork-me-on-github
# Items related to the handling of the files
files:
    # same as old "skip_files"
    skip:
        - .+\\.pyc
        - __pycache__
        - \\.travis.yml
        - \\.git
        - \\.DS_Store
    # same as old "copy_files"
    copy:
        - pyccoon.svg
        - pyccoon_icon.svg
        - .+\\.html
        - .+\\.css
        - \\.pyccoon
# Items related to generating the HTML docs
documentation:
    mathjax: true
    # default is "pre-wrap", since we are breaking backward compatibility anyway;
    # old default was "normal"
    linebreaking-behavior: default
    # can be either "side-by-side", "linear" or
    # a path to a HTML pystache template.
    template: side-by-side
    # a CSS file; can be either not specified (or "default")
    # or a path to a CSS file.
    # There could be standard styles too, such as
    # "dark", "grayscale", etc.
    style: default

I think that having a proper nested file with categories is much better for future extensibility and clearer for the user.

The config file could also use JSON instead of YAML, but I think the version above is much preferrable to this (which can't even contain comments):

{
  "project": {
    "name": "pyccoon v0.1.4 documentation",
    "banner": "fork-me-on-github"
    },
  "file": {
    "skip": [
        ".+\\.pyc",
        "__pycache__",
        "\\.travis.yml",
        "\\.git",
        "\\.DS_Store"
        ],
    "copy": [
        "pyccoon.svg",
        "pyccoon_icon.svg",
        ".+\\.html",
        ".+\\.css",
        "\\.pyccoon"
        ],
  },
  "documentation": {
    "mathjax": true,
    "linebreaking-behavior": "default",
    "template": "side-by-side",
    "style": "default"
    }
}

Do you think it would be worth it to break backward compatibility for this?
I think it would, since it makes it easier to extend pyccoon in the future, and I don't think pyccoon has that many users yet.

[ckald]

Yeah, I was going to restructure the JSON config, but comments is a killer feature. Let's do that instead, but in a new branch — it will be Pyccoon 1.x, as contains major changes. All the current stuff can be also published as Pyccoon 0.x