sassdoc / sassdoc-theme-default Goto Github PK

From @Undistraction (reference).

https://github.com/SassDoc/sassdoc-theme-default/blob/master/views/layouts/base.html.swig#L3-L4

We implemented @content but never used it in the theme... I forgot. :x

To reproduce; run sassdoc on this:

/// My selector
.class {
  display: block;
}

It shows up as this:

I believe that it tries to pluralize it like it does for mixin => mixins, variable => variables, and is trying css => csss.

Please let me know if this should go in the main sassdoc repo. Great work on this; thanks!

Added some tests of @alias after reviewing the coverage results, as for SassDoc/sassdoc#335

Found that:

• "Refer to" is broken.
• When an aliased item is not found, SassDoc warns accordingly, but should we still display the "alias for" on the title right hand ?

Moved from https://github.com/SassDoc/sassdoc-theme-light/issues/21.

If we have, let's say, foo/index.html in the destination directory, and it extends the base layout, all assets URLs will be fucked up because they will search for foo/assets/* instead of ../assets/*.

We need to compute the relative path to the root directory (.. in the above case) and pass it as a variable in the views. Maybe this should be a feature of Themeleon?

What do you think, @SassDoc/owners?

If Themeleon can provide an helper for this, it would obviously be nice.
On the other hand, if a theme is willing to used fancy structures, maybe it should its own responsibility to deal with this ?

Could you give us a little example how this would work ?

I wouldn't call it a "fancy structure". A website with more than one page looks kind of elementary to me.

If I add this in Themeleon, I'll need to "hook" all template engines mixins to do the following:

• If the destination path is relative, count the number of subdirectories.
• Add a ctx.base key containing as much ../ as needed to go to the root destination directory.

In a view, we would do:

<link href="{{ base }}/assets/css/main.css" rel="stylesheet">
<img src="{{ base }}/assets/img/troll.png">

I added an helper in Themeleon's develop branch for this.

The next step is to package the official mixins in the core, and I think this will all be good for Themeleon 2.0!

BTW I've done a bit of refactoring on Themeleon, and I've got a start for a common test structure.

When there are no items, it looks like shit.

Changed annotation names:

• @parameters => @parameter
• @requires => @require
• @returns => @return
• @throws => @throw
• @todos => @todo
• @prop => @property

So apparently Swig is deprecated and not maintained anymore, hence a nice warn in the shell while installing SassDoc.

I guess we should migrate to another engine. Nunjucks is great and pretty close to Swig syntaxically.

https://github.com/SassDoc/sassdoc-theme-default/blob/master/views/includes/annotations/preview.html.swig#L22

I too would like to use standard as my comrads, please @hugogiraudel ;)

Link in the readme is broken.

Hey hey,
I see that in the default theme the output for a mixin is placed before output.

To me it would make more sense to show the example first, and then the output that example results in. For example:

Example:

@include foo-bar('red');

Output

.baz {
  border: 1px red;
  color: red;
  text-transform: uppercase;
}

Is there a use case I'm overseeing in which output would make sense to put before the example?

Cheers,
Marco

From @Undistraction (reference).

From @Undistraction (reference).

Ref: #20.

Still. :(

1. Change link URL to head to official site;
2. Use inline logo rather than plain text.

As of today, we consider variable content safe. This can lead to some issues when using <html-tags> within a string, because it's getting output.

Moved from SassDoc/sassdoc#377

Hello,

the deprecated label in the docs seems to be broken, as you can see here:

I tried it both with and without a description... or am I missing something?
I'm on a Mac with Chrome.

Thomas

To support this SassDoc#261 We need to update the theme. Removing things like:

{% if item.return %}
  {{ return[0].type }} {{ return[0].description }}
{% endif %}

Moved from SassDoc/sassdoc#325.

@andge

there are many files in the folder .so when i generate the doc through sassdoc,there are no info aboat where the mixin is from.

so,can you support it ?

thank you

@valeriangalliat

Hi @andge,

There's a feature kinda similar to what you want; if you configure a basePath (see Customizing The View) so SassDoc can link to your file URL, by adding a "View source" link near your "items", linking to {{ basePath }}/{{ filePath }}.

However it might be an interesting idea to display the actual file path in the documentation (not just a "View source" link), and this wouldn't even require a basePath to be set (but if one is set, we can make it a link too, and maybe remove the actual "View source"). Opinions on this @SassDoc/owners?

@pascalduez

At the very beginning we had a "found at" thing displayed in the theme, is that still implemented ?

From @Undistraction (reference).

Anchor references IDs part the "General" group get an undefined for group.

When we have to display a data type (for a variable, a parameter or whatever), we use to have something like this in our templates:

<code>{{ type | split('|') | trim | capitalize | join('</code> or <code>') | safe }}</code>

We have this monstrosity at several places. Could we have a little custom function to allow us to do something like:

{{ type | display_as_type }}

Ping @SassDoc/owners.

When loading via https, jQuery and the webfonts are not loaded due to mixed content warnings.

I've prepared a PR you can easily merge: #90

Add tracking key, containing a HTML string to be injected in the DOM. What is best? Content to be injected in a script tag? Or HTML string directly?

Add googleAnalytics helper.

/// hey
/// @example
///   @include mixin($arg);

We should give a try at pruning the first level indentation since it's rendered in the theme.

Following of SassDoc/sassdoc#256

• Add a description (or fullDescription or whatever) key to the configuration
• If it is a string, parses it as Markdown
• if it is a path, get content and parses it as Markdown

Following @FWeinb proposal on Slack.

let the user define a base color via config and then calculate needed permutations

A placeholder is grouped in @buttons

/// Button generic styles
/// @group buttons
%bttn-generic {}

When I click on it in left side bar it anchors to

./index.html#buttons-placeholder-bttn-generic

and it is fine.

But when I navigate to the variable that is used by the very same placeholder and click on ‘Used by’ link it anchors to

./index.html#placeholder-bttn-generic

which is incorrect.

Same applies to all documented items that were grouped.

My config .sassdocrc file:

exclude:
  - sass/vendor/*
shortcutIcon: static/img/favicon.ico
groups:
  buttons: Buttons
  color-palette: Color Palette
  buttons: Buttons
  labels: Labels
  font-family: Font Family
  undefined: General

g-doc file:
http://tinyurl.com/qytt28q

It would be nice if the sassdoc detected that a color is being used as a value of a variable. It should then output a tile with the configured color.

/**
 * The theme color used for creating a color range.
 * @type color
 */
$theme-color: rgb(85,128,182) !default;

Moved from SassDoc/sassdoc#416

The current styling on the @SInCE annotation is quite strange.
It's put on the right side, above the actual element, which sometimes makes it look like it belongs to something else.

Example:

Here the "since 1.0.2" is actually part of the variable $colors, but it looks like it belongs to "Variables".

Can we please add it inline with the variable/function name?

E.g. "Colors - since v1.0.2"

We do no longer have html* properties (see #3).

Since PR #84 modified the markup of each section to include the group in the id attribute, this change breaks the search suggestions feature, since generated anchors are no longer valid.

One way to solve this could be to modify this file:

  Search.prototype.initialize = function () {
    // Fuse engine instanciation
    this.index = new Fuse($.map($(this.conf.search.items), function (item) {
      var $item = $(item);

      return {
        group: $item.data('group'), // <=== To include group
        name: $item.data('name'),
        type: $item.data('type'),
        node: $item
      };
    }), this.conf.fuse);

    this.initializeSearch();
  };

And here:

  Search.prototype.fillSuggestions = function (items) {
    var searchSuggestions = $(this.conf.search.suggestionsWrapper);
    searchSuggestions.html('');

    var suggestions = $.map(items.slice(0, 10), function (item) {
      var $li = $('<li />', {
        'data-group': item.group,
        'data-type': item.type,
        'data-name': item.name,
        'html': '<a href="#' + item.group + '-' + item.type + '-' + item.name + '"><code>' + item.type.slice(0, 3) + '</code> ' + item.name + '</a>'
      });

      searchSuggestions.append($li);
      return $li;
    });

    return suggestions;
  };

And add this new data-group attribute to each .sassdoc__item here:

<li class="sidebar__item  sassdoc__item" data-group="{{ group_name }}" data-name="{{ item.context.name }}" data-type="{{ item.context.type }}">

I'm getting the following error when using the latest sassdoc and sassdoc-theme-default

Error: Cannot find module '6to5-runtime/helpers'
    at Function.Module._resolveFilename (module.js:336:15)
    at Function.Module._load (module.js:278:25)
    at Module.require (module.js:365:17)
    at require (module.js:384:17)
    at Object.<anonymous> (/Users/ronedgecomb/code/wk/bcc/wk.css/node_modules/sassdoc/node_modules/sassdoc-theme-default/dist/swig.js:3:19)
    at Module._compile (module.js:460:26)
    at Object.Module._extensions..js (module.js:478:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Module.require (module.js:365:17)
    at require (module.js:384:17)

Here is a look at the dependencies that were installed.

[email protected] node_modules/sassdoc
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected]
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected], [email protected])
├── [email protected] ([email protected], [email protected], [email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected], [email protected], [email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected], [email protected])
├── [email protected] ([email protected])
└── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected])

Any help would be greatly appreciated, thanks!

This looks confusing. We should add the type of the required/used item.

Moved from SassDoc/sassdoc#436

A colour variable referencing another colour variable is not getting the rendered preview.

/// Links color
/// @type Color
$link-color: $primary-color !default;

It's been already evoked in this comment.

@FWeinb suggestion:

This should in fact be possible. We might need to add some helper methods to SassDoc-extras to generate a variable-value map and than use that to get the color. This implies that the used variable is in fact documented using SassDoc.

No .sassdoc destination dir exist.
env.theme('.sassdoc', env).catch(console.log); --> []

No theme/assets source dir exist.
env.theme('.sassdoc', env).catch(console.log); --> []

fs-extra dependency is 0.1.0 which is pretty low, latest is 0.16.3.
And in this version copy = ncp
There something screwed in the way ncp pass errors to callbacks.

Solution, uptate to [email protected]. At least there's an Error returned on source fail.

fs-extra.copy only error if the source is erroneous, if the destination does not exist it just silently exit.

Solution, add a fs.exist(dest) test before ?

Ref.

Currently the X button to close the sidebar is located on the header. This is confusing and I would expect a button in this location to close the header, not the sidebar.

The button should be located in the sidebar and the icon should be changed to a left-facing arrow (or similar). Another option would be to display it as a kind of tab in the vertical centre of the border between sidebar and main content.