Although it is explicit with styleguide-metas[..] and styleguide-reference-[...] this could seems a little bit longer some ones.

Either we allow to customize RULE_BASE_PREFIX, RULE_META, RULE_META_REFERENCES from nomenclature module, either we enable to use a shorten variant like sg-metas[...] and sg-ref[...].

The most important thing to consider first is how we allow to change this behavior, since it is not a Django project there is nothing like the easy "settings way" or we will have to implement it. A simple way would be to do this on Manifest instance, but it would be nice that CSS manifest have a hint about it.

In practice this begins to be tedious to enable every reference in metas, an automatic mode would be cool.

Something like ::

.styleguide-metas-references{
    --auto: "true";
}

And serializer will know it just have to accept every rule starting with styleguide-reference- and ignore --names variable when reading meta-references.

Probably have missed something, the flat structure does not turn to an OrderedDict, just a simple dict, resulting in datas does not hold its order from manifest values.

Perform flake8 inspection and fix errors.

I thought it could not be an issue since we were told dart-sass was compatible with scss sources developed with libsass (except for some specific things like division or extend that have been documented in migration document).

Sadly it is not..

So some code like:

.styleguide-reference-bt_palette{
    --structure: "flat";
    --splitter: "json-list";
    --keys: '#{get-names-to-json($colors)}';
    --values: '#{get-values-to-json($colors)}';
}

With libsass is compiled to:

.styleguide-reference-bt_palette {
  --structure: "flat";
  --splitter: "json-list";
  --keys: '["blue", "indigo", "purple"]';
  --values: '["#0d6efd", "#6610f2", "#6f42c1"]';
}

But with dart-sass the source will compile to:

.styleguide-reference-bt_palette {
  --structure: "flat";
  --splitter: "json-list";
  --keys: "["blue", " indigo", " purple"]";
  --values: "["#0d6efd", " #6610f2", " #6f42c1"]";
}

It involves two issues:

• Simple quote is turned to double quotes, since we already use double quote to surround item, this a breaking change which lead to totally invalid CSS;
• Each item is always prefixed with a string;

Since the manifest helper functions are a little bit tricky, i currently don't see a clue yet how to fix it and i can't even say if we can fix it without breaking compatibility with libsass.

Since version 1.0.0, tinycss2 has fixed behavior with double dash to be correctly parsed.

In py-css-styleguide we fixed this behavior on our own but now with tinycss2>=1.0.0 it leads to fail to properly read manifest and raise error on reading manifest.

We have to remove our own fix and define tinycss2 minimal version to 1.0.0 in package setup (actually there is no pinned version which cause this issue on recent project install).

Quick fix for impatient just pin tinycss2 version in your requirement or manually install it before instally py-css-styleguide.

Actually with the --auto value enabled from styleguide-metas-references rule there is no way to disable some reference, either all reference are taken or we need to manually define each enabled one in --names.

We need a way to explicitely disable references. Disabled reference should be excluded from enabled reference after they are extracted either from the automatic or/and manually options.

In documentation:

https://pycssstyleguide.readthedocs.io/en/latest/basics.html#flat

Structure value is:

--structure: "true";

It should be instead:

--structure: "flat";

Module is listed in Core API documentation but empty, at least the docstring should be published in docs and a basic sample usage also.

This should contain default settings, a view, urls and basic template to quickly start using styleguide from Django.

Actually, serializer internally use dictionnary in many structure case and so iterating on manifest reference have arbitrary order.

It means even a map of items is defined like tiny small normal big, from manifest it could be ordered like small big normal tiny. This results to unordered items in styleguide.

JSON structure serializer and list separator rules require to be quoted with single quote, since JSON is using double quote and a common mistake is to use double quote around rule like this:

--values: "#{get-values-to-json($colors)}";

Which will turn in CSS to:

--values: "["foo", "bar", "ping pong"]";

And leads to unexpected issues with styleguide parser (sometime with an error unrelated to the quotes).

The documentation should use a warning block to remember to use only single quotes around rule like this:

--values: '["foo", "bar", "ping pong"]';

It may be more resilient for generic manifest on library (like Sveetoy) when some user settings are empty.

Actually a generic manifest would have to be corrected manually to avoid errors from empty settings that user dont want/need.

A convenient helper to get all rules in a dictionnary, to avoid to use to_json() in Python code.

Also to_json() should use to_dict() to build its items.

Avoid to perform loop and so nth() usage when given list is empty, since it raises an libsass error.

It may be useful sometime to serialize some numeric value to a numeric value, something which should be able to store either an integer or a float.

If values from a list contain space it causes trouble for serializer trying to separate it and leads to an error like:

Flat reference have different length of 'keys' ands 'values' variable

Aka if i write some gradient background, the background property value will possibly have space, like:

linear-gradient(to top, $lightseagreen1, $lightseagreen10 1px, $lightseagreen45 1px, $lightseagreen45)

If the CSS manifest lists agregate backgrounds values in some list, the previous mentionned error will raise from serializer.

We need a solution, since this a common usage to have those kind of CSS values.

Quick solution maybe to add feature for custom separator but it may not be a perfect stable solution for every cases.

This is at least occuring with list-to-json usage.

Like if we try to turn a list of background properties which contains quote like center left / cover no-repeat url('theme/bg-commitment-quality.jpg') to a pseudo json list in manifest.

Then the serializer will choke on this pseudo JSON, since it contains quotes which are used as value surrounding. Using simple quote instead of double quote does not resolve issue, since it is used as the pseudo json surrouinding and also libsass transform them to double quote. Also finally we can't recommend to not use quotes since it is sometime required like in a background url.