Add footer #57

Closed
HugoGiraudel opened this Issue Jul 7, 2014 · 10 comments

Comments

Projects
None yet
4 participants
@HugoGiraudel
Member

HugoGiraudel commented Jul 7, 2014

I want to add a footer to generated docs. Not only will it contain a small "Built with SassDoc" link on the right, but also informations about the documented project on the left, given from view.json.

@pascalduez and I thought about:

// view.json
"project": {
  "name": "My Awesome Project",
  "url": "http://my-awesome-project.com",
  "license": "MIT",
  "version": "1.3.37"
}
<footer class="sassdoc__footer">
  <div class="container">
    {% if project %}
      <div class="sassdoc__footer-project">
        <!-- Name and URL -->
        {% if project.url %}
          <a href="{{ project.url }}">{{ project.name }}</a>
        {% else %}
          <span>{{ project.name }}</span>
        {% endif %}

        <!-- Version -->
        {% if project.version %} - {{ project.version }}{% endif %}

        <!-- License -->
        {% if project.license %}, under {{ project.license }}{% endif %}
      </div>
    {% endif %}

    <span class="sassdoc__footer-watermark">Built with <a href="https://github.com/HugoGiraudel/SassDoc">SassDoc</a>.</span>
  </div>
</footer>

In case you wonder, both version and title keys from view.json would be moved to project object.

Is everybody okay with this? @valeriangalliat, @FWeinb?

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 7, 2014

Member

It would be great to have a project description, below the documentation map, and why not in Markdown.

"project": {
  ...
  "description": "path/to/project.md"
}

Also I think the "Build with SassDoc" link should be optionally removable.

As an improvement, there could be a link for the license. This requires to maintain a list of common licenses links, but maybe there's a Node module for this.

Member

valeriangalliat commented Jul 7, 2014

It would be great to have a project description, below the documentation map, and why not in Markdown.

"project": {
  ...
  "description": "path/to/project.md"
}

Also I think the "Build with SassDoc" link should be optionally removable.

As an improvement, there could be a link for the license. This requires to maintain a list of common licenses links, but maybe there's a Node module for this.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 7, 2014

Member

Should the default project values be empty or SassDoc's informations?

"project": {
  "name": "SassDoc",
  "url": "https://github.com/HugoGiraudel/SassDoc",
  "version": "1.0.0-rc.9",
  "license": "MIT",
  "description": "Like JSDoc, for Sass files."
}
Member

HugoGiraudel commented Jul 7, 2014

Should the default project values be empty or SassDoc's informations?

"project": {
  "name": "SassDoc",
  "url": "https://github.com/HugoGiraudel/SassDoc",
  "version": "1.0.0-rc.9",
  "license": "MIT",
  "description": "Like JSDoc, for Sass files."
}

@HugoGiraudel HugoGiraudel self-assigned this Jul 7, 2014

@HugoGiraudel HugoGiraudel referenced this issue Jul 7, 2014

Closed

Add license #58

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Jul 7, 2014

Member

Maybe the format shoud be the same as a package.json
So allowing the inclusion of the issue tracker repo

Member

FWeinb commented Jul 7, 2014

Maybe the format shoud be the same as a package.json
So allowing the inclusion of the issue tracker repo

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 7, 2014

Member

@HugoGiraudel If you have not yet configured the project informations, I don't think you want to have SassDoc's informations instead... I'd prefer empty values, or rather dummy values:

  • Name: DummyProject
  • Version: 1.3.37
  • URL: https://dummy.project/
  • License: Beerware (or maybe empty to not force the users to provide a license — even if they should)
  • Description: (empty)
Member

valeriangalliat commented Jul 7, 2014

@HugoGiraudel If you have not yet configured the project informations, I don't think you want to have SassDoc's informations instead... I'd prefer empty values, or rather dummy values:

  • Name: DummyProject
  • Version: 1.3.37
  • URL: https://dummy.project/
  • License: Beerware (or maybe empty to not force the users to provide a license — even if they should)
  • Description: (empty)
@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 7, 2014

Member

Okay, here is what I have in mind.

{
  "display": {
    "access": ["public", "private"],
    "alias": false,
    "sassdoc": true
  },

  "package": "./package.json"
}
  1. Find configuration file with --config option from the CLI
  2. If --config is not set or resolve to an unknown path, warn and fallback to ./view/view.json
  3. Get file at path specified in package key
    • If it resolve to a valid path, redefine package key with the content of the file (an object)
    • If it does not resolve to a valid path, warn and leave package as is (which is not an object)
Member

HugoGiraudel commented Jul 7, 2014

Okay, here is what I have in mind.

{
  "display": {
    "access": ["public", "private"],
    "alias": false,
    "sassdoc": true
  },

  "package": "./package.json"
}
  1. Find configuration file with --config option from the CLI
  2. If --config is not set or resolve to an unknown path, warn and fallback to ./view/view.json
  3. Get file at path specified in package key
    • If it resolve to a valid path, redefine package key with the content of the file (an object)
    • If it does not resolve to a valid path, warn and leave package as is (which is not an object)
@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 7, 2014

Member

I like that.

Throw an error if the given config file does not exists (or is not readble or any I/O error) instead of failing silently with a default value. Take the default only only if there is no --config. Same for package.

Member

valeriangalliat commented Jul 7, 2014

I like that.

Throw an error if the given config file does not exists (or is not readble or any I/O error) instead of failing silently with a default value. Take the default only only if there is no --config. Same for package.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Jul 7, 2014

Member

Would be interesting to be able to pass either an object or a path to package.
There are situations, where the content of package.json is already loaded, and available as an object.
So no need to do some I/O again.

Member

pascalduez commented Jul 7, 2014

Would be interesting to be able to pass either an object or a path to package.
There are situations, where the content of package.json is already loaded, and available as an object.
So no need to do some I/O again.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 7, 2014

Member

Agreed. I'm on it.

Member

HugoGiraudel commented Jul 7, 2014

Agreed. I'm on it.

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
Member

valeriangalliat commented Jul 7, 2014

+1

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 7, 2014

Member

Deployed in rc.10.

Member

HugoGiraudel commented Jul 7, 2014

Deployed in rc.10.

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