Explicit reference names

With this way, we don’t use automatic description and instead explicitely define every references we want for description. Obviously you will have to maintain correctly the name list to ensure they exists in references.

Write a Sass file that will use the helpers and settings to build a CSS manifest:

@charset "UTF-8";

@import "settings";

@import "styleguide_helpers";

.styleguide-metas-compiler {
    --support: "#{$pycssstyleguide-compiler-support}";
}

.styleguide-metas-references {
    --names: "palette version";
}

.styleguide-reference-palette {
    --structure: "flat";
    --keys: "#{get-names($palette)}";
    --values: "#{get-values($palette)}";
}

.styleguide-reference-schemes {
    --structure: "nested";
    --splitter: "object-list";
    --keys: '#{get-names-to-json($schemes-colors)}';
    --selector: '#{get-names-to-json($schemes-colors, '.bg-')}';
    --background: '#{get-props-to-json($schemes-colors, 'background')}';
    --font_color: '#{get-props-to-json($schemes-colors, 'font-color')}';
}

.styleguide-reference-borders {
    --structure: "nested";
    --keys: "#{get-names($borders)}";
    --size: "#{get-props($borders, 'size')}";
    --style: "#{get-props($borders, 'style')}";
    --color: "#{get-props($borders, 'color')}";
}

.styleguide-reference-gradients {
    --structure: "object-complex";
    --object: '["#{to-string(map-values($gradients), $glue: '", "')}"]';
}

.styleguide-reference-grid_cell_sizes {
    --structure: "flat";
    --keys: "#{floor-number-items($grid-cell-sizes)}";
    --values: "#{to-string($grid-cell-sizes, $glue: ' ')}";
}

.styleguide-reference-spaces {
    --structure: "list";
    --items: "#{to-string($spaces, $glue: ' ')}";
}

.styleguide-reference-version {
    --structure: "string";
    --value: "#{$version}";
}

Note

From styleguide-metas-references we explicitely define the allow reference names to serialize within rule --names: "...".

Build CSS manifest with your Sass compiler and you should get:

/* Helper functions from py-css-styleguide==1.0.0 */
.styleguide-metas-compiler {
  --support: "libsass";
}

.styleguide-metas-references {
  --names: "palette version";
}

.styleguide-reference-palette {
  --structure: "flat";
  --keys: "black white grey";
  --values: "#000000 #ffffff #404040";
}

.styleguide-reference-schemes {
  --structure: "nested";
  --splitter: "object-list";
  --keys: '["black", "grey", "white", "grey-gradient", "with-image"]';
  --selector: '[".bg-black", ".bg-grey", ".bg-white", ".bg-grey-gradient", ".bg-with-image"]';
  --background: '["#000000", "#404040", "#ffffff", "linear-gradient(#ffffff, #ffffff 85%, #404040)", "url(\u0022foo/bar.png\u0022)"]';
  --font_color: '["#ffffff", "#ffffff", "#000000", "#000000", "#000000"]';
}

.styleguide-reference-borders {
  --structure: "nested";
  --keys: "thin normal bold";
  --size: "rem-calc(1px) rem-calc(3px) rem-calc(5px)";
  --style: "solid solid solid";
  --color: "white white black";
}

.styleguide-reference-gradients {
  --structure: "object-complex";
  --object: '["linear-gradient(#f69d3c, #3f87a6)", "radial-gradient(#f69d3c, #3f87a6 50px)"]';
}

.styleguide-reference-grid_cell_sizes {
  --structure: "flat";
  --keys: "5 25 33 75 100";
  --values: "5 25 33.3333 75 100";
}

.styleguide-reference-spaces {
  --structure: "list";
  --items: "tiny short normal large wide";
}

.styleguide-reference-version {
  --structure: "string";
  --value: "42.0";
}

Then load this manifest with script styleguide.py and it will return this JSON:

{
    "metas": {
        "compiler_support": "libsass",
        "references": [
            "palette",
            "version"
        ],
        "created": "2012-10-15T10:00:00"
    },
    "version": "42.0",
    "palette": {
        "black": "#000000",
        "white": "#ffffff",
        "grey": "#404040"
    }
}