Automatic with name exclusions

This way is still in “automatic describing all references” but you are able to exclude some 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 {
    --auto: "true";
    --excludes: "schemes borders gradients grid_cell_sizes spaces 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 require to serialize every existing references with rule --auto: "true" but ignoring some names within rule --excludes: "...".

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 {
  --auto: "true";
  --excludes: "schemes borders gradients grid_cell_sizes spaces 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"
        ],
        "created": "2012-10-15T10:00:00"
    },
    "palette": {
        "black": "#000000",
        "white": "#ffffff",
        "grey": "#404040"
    }
}