Best practice for arbitrary content

[whmii]

Hi 👋

I'm wondering what the best practice for arbitrary content is. I am looking to add installation instructions/ get started guide to my proj. While I know I can add this content directly to the theme, I would reeeeeeeeaaallly prefer to have it as part of the project repository. I was wondering if there was a particular way to do this correctly or if there was some support for arbitrary documentation that does not correspond to a particular mixin or function.

[pascalduez]

Hi,

give a try to the description or descriptionPath configuration keys: http://sassdoc.com/extra-tools/#description-description-descriptionpath

In SassDoc's default theme this will output the content at the top.

[whmii]

in the data file should that look something like this?

[
  {
    "description": "My super cool project description blah sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
  },
  {
    "description": "Determine if a column count has been given.\nIf no columns have been given return the grid's total column count.\n\n",
    "commentRange": {
      "start": 2,
      "end": 14
    },
    "context": {
      "type": "function",
      "name": "_neat-column-default",
      "code": "\n  @if $columns == null {\n    $_grid-columns: _retrieve-neat-setting($grid, columns);\n    @return $_grid-columns;\n  } @else {\n    @return $columns;\n  }\n",
      "line": {
        "start": 16,
        "end": 23
      }
      …

I feel like i'm missing something since the proj description object is on the same level as all of the feature definitions. I'm not using middleman with the sass-doc cli instead of a sass-doc theme.

I would like to have it in the project repository so that I can version my get started guide based on the release.

"theme" (middleman app) https://github.com/thoughtbot/neat.bourbon.io project https://github.com/thoughtbot/neat/tree/neat-2.0.0

In an ideal world, I can put a big ol comment somewhere in https://github.com/thoughtbot/neat/blob/neat-2.0.0/core/_neat.scss that has an arbitrary markdown section in which I can place a getting started section that gets generated to something specific by the cli that I can hook in to in the site app.

[whmii]

Sorry this is continues to be a bit vague. I would even be fine with defining an arbitrary doc item like the following:

/// My super cool project description blah sit amet, consectetur adipisici.
///
/// Some more content of stuff.
///
/// @name Getting started 2

But in that case I would still need to do something like following this block with an arbitrary item definition like…

/// My super cool project description blah sit amet, consectetur adipisici.
///
/// Some more content of stuff.
///
/// @name Getting started 2

$neat-getting-started: null !default;

… which seams like not the right thing to do.

[KittyGiraudel]

As @pascalduez said, the description or descriptionPath keys should achieve what you want. We introduced them for that purpose specifically: providing project wide instructions and information. When used, you should get a description key in the final data (outside of any item) that you can output in your theme (and is automatically output in the default theme).

[whmii]

ah, sorry for leaving this open, thanks for the comments