Add ability to describe an introduction text #256

Closed
Undistraction opened this Issue Oct 11, 2014 · 15 comments

Comments

Projects
None yet
5 participants
@Undistraction

It would be great to be able to add an Introduction to the documentation. just something to sit above the generated docs in the main column (in the default theme).

If I have a README outlining how the library should be used and full of examples, it would seem to me this should be something that I can include into the docs as an introduction. I'd love to be able to just direct to the Sassdoc from the README, but pure docs without context mean I'm going to end up boiling a lot of the docs down into the README. Being able to consolidate intro and docs would make both docs and introduction stronger.

This could be expanded to allow links from the intro to the relevant docs (perhaps just parsing out known entities from the text and adding links automagically).

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 11, 2014

Member

If we want to add an introduction text, we will probably keep it very simple: a string parsed as Markdown, injected into the DOM. I'm okay with that.

Edit: depending on the outcome of this issue, we'll move it to sassdoc-theme-default since it is strictly related to the theme at this point.

Member

HugoGiraudel commented Oct 11, 2014

If we want to add an introduction text, we will probably keep it very simple: a string parsed as Markdown, injected into the DOM. I'm okay with that.

Edit: depending on the outcome of this issue, we'll move it to sassdoc-theme-default since it is strictly related to the theme at this point.

@HugoGiraudel HugoGiraudel added this to the 2.1 milestone Oct 11, 2014

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Oct 12, 2014

Member

Maybe we could even allow to include a README.md right from the project root.

Member

FWeinb commented Oct 12, 2014

Maybe we could even allow to include a README.md right from the project root.

@Undistraction

This comment has been minimized.

Show comment
Hide comment
@Undistraction

Undistraction Oct 12, 2014

I think a choice of either the README or the name of a .md file would be perfect.

I think a choice of either the README or the name of a .md file would be perfect.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 12, 2014

Member

Maybe we could even allow to include a README.md right from the project root.

I don't like this. I don't want people to write their README in some way because of SassDoc. Although we could allow either a markdown file (if string is a path), or a description as a string directly.

Member

HugoGiraudel commented Oct 12, 2014

Maybe we could even allow to include a README.md right from the project root.

I don't like this. I don't want people to write their README in some way because of SassDoc. Although we could allow either a markdown file (if string is a path), or a description as a string directly.

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Oct 13, 2014

Member

Adding the ability to put a path in the configuration file is fine with me. Do we move this to the default theme?

Member

FWeinb commented Oct 13, 2014

Adding the ability to put a path in the configuration file is fine with me. Do we move this to the default theme?

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment

@HugoGiraudel HugoGiraudel changed the title from Support for Introduction Text to Add a way to describe an introduction text Oct 13, 2014

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
Member

valeriangalliat commented Oct 13, 2014

Yep.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Oct 13, 2014

Member

A path in config is fine. Let's go !

Member

pascalduez commented Oct 13, 2014

A path in config is fine. Let's go !

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 13, 2014

Member

Alright, so the scenario is:

  • try require() on view.description;
    • if it works, put content from required file in view.description;
    • if it fails, quit (view.description is already a description).
  • parse it as Markdown with sassdoc-extras;
  • display it in sassdoc-theme-default on top of main container;
  • write docs.

Who takes it? I can take the theme/docs stuff.

Member

HugoGiraudel commented Oct 13, 2014

Alright, so the scenario is:

  • try require() on view.description;
    • if it works, put content from required file in view.description;
    • if it fails, quit (view.description is already a description).
  • parse it as Markdown with sassdoc-extras;
  • display it in sassdoc-theme-default on top of main container;
  • write docs.

Who takes it? I can take the theme/docs stuff.

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Oct 13, 2014

Member

require is only for JavaScript or JSON files… and you want a string back. You want something like module.exports = 'description';?

Or you probably mean fs.readFile.

Member

valeriangalliat commented Oct 13, 2014

require is only for JavaScript or JSON files… and you want a string back. You want something like module.exports = 'description';?

Or you probably mean fs.readFile.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Oct 13, 2014

Member

You get the idea. If it's a path, get content, else treat content as content.

Member

HugoGiraudel commented Oct 13, 2014

You get the idea. If it's a path, get content, else treat content as content.

@HugoGiraudel HugoGiraudel changed the title from Add a way to describe an introduction text to Add ability to describe an introduction text Nov 26, 2014

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Feb 4, 2015

Member

Regarding this (part of 2.1), there is something I don't like much. When taking an actual package.json file as a package, there is absolutely no way that the description ends up being a path to a Markdown file. This is not how description works as per the package spec or whatever you want to call this.

Member

HugoGiraudel commented Feb 4, 2015

Regarding this (part of 2.1), there is something I don't like much. When taking an actual package.json file as a package, there is absolutely no way that the description ends up being a path to a Markdown file. This is not how description works as per the package spec or whatever you want to call this.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Feb 7, 2015

Member

What would be the best way to tackle this one? I'm thinking of:

  • 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

Thoughts @SassDoc/owners?

Member

HugoGiraudel commented Feb 7, 2015

What would be the best way to tackle this one? I'm thinking of:

  • 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

Thoughts @SassDoc/owners?

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Feb 7, 2015

Member

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

Looks perfect. Exactly what I had in mind.

Member

pascalduez commented Feb 7, 2015

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

Looks perfect. Exactly what I had in mind.

@pascalduez pascalduez referenced this issue in SassDoc/sassdoc-theme-default Feb 8, 2015

Closed

Add ability to describe an introduction text #66

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Feb 8, 2015

Member

It's a theme feature.
Moved to SassDoc/sassdoc-theme-default#66

Member

pascalduez commented Feb 8, 2015

It's a theme feature.
Moved to SassDoc/sassdoc-theme-default#66

@pascalduez pascalduez closed this Feb 8, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment