Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Things TODO. Read this if you want to help.

  • Loading branch information...
commit 63e4df63fbc35180a29d9e07da2e68c17ec45845 1 parent 37c2ac7
Chris Eppstein authored February 22, 2009

Showing 1 changed file with 76 additions and 0 deletions. Show diff stats Hide diff stats

  1. 76  TODO.markdown
76  TODO.markdown
Source Rendered
... ...
@@ -0,0 +1,76 @@
  1
+Here's the things this project needs in order to make it decent:
  2
+
  3
+# Core Architecture
  4
+
  5
+## Tree Awareness
  6
+
  7
+The command line tool currently only operates on individual files, it should be able to accept
  8
+a directory and recurse. It would assume the directory provided is the top level for an import
  9
+directive.
  10
+
  11
+## Manifest
  12
+
  13
+The tool should be able to build a manifest of files, constants, and mixins for use in creating
  14
+a table of contents.
  15
+
  16
+## Output Formats
  17
+
  18
+Implement a visitor pattern that can visit a manifest, file, mixin, or constant and emit
  19
+the correct output for it that matches a particular output format. 
  20
+This can be used for generating html, plain text, pdf, or whatever.
  21
+
  22
+## Templates and Layouts
  23
+
  24
+For at least the html generator, a user should be able to specify templates for the given
  25
+type and a layout for files to add headers, footer, etc. It would be awesome if these were
  26
+be written in haml, the stylesheets in Sass (using compass of course!) and then compiled into
  27
+html and css.
  28
+
  29
+## Documentation Queries
  30
+
  31
+There should be a mode of operation where a user can request plain text documentation on the
  32
+command line for a particular code artifact. It might look something like this:
  33
+
  34
+    $ sassdoc --compass -q +alternating-rows-and-columns path/to/project/sass/files
  35
+    Mixin: +alternating-rows-and-columns(even_row_color, odd_row_color, dark_intersection[, header_color, footer_color])
  36
+    --------------------------------------------------------------------------------------------------------------------
  37
+    Sets background colors for a table so that rows and columns alternate and are shaded
  38
+    correctly.
  39
+    
  40
+    Parameter: even_row_color
  41
+      The color of even rows. Even rows must have the .even class on them
  42
+    Parameter: odd_row_color
  43
+      The color of odd rows. Odd rows must have the .odd class on them.
  44
+    Parameter: dark_intersection
  45
+      This color will be subracted from the row color for even columns.
  46
+    Parameter: header_color (default value: white)
  47
+      The color of the header.
  48
+    Parameter: footer_color (default value: white)
  49
+      The color of the footer.
  50
+    
  51
+
  52
+## Implementation of Core Architecture
  53
+
  54
+It's possible that much of this can be built on top of rdoc or some other code documentation tool
  55
+by implementing a parser plugin. I'm open to that possibility but I think it's a long shot.
  56
+
  57
+# Implementation Details
  58
+
  59
+## CLI
  60
+
  61
+The CLI needs to be made more robust:
  62
+
  63
+* It should accept import paths like the sass CLI does.
  64
+* Trap and report sass parser errors nicely.
  65
+
  66
+## Frames Suck
  67
+
  68
+Every code documentation tool uses framesets for it's output. This shouldn't be one of them. Frames blow because they make landing from a search engine a horrible experience. I like the [reference documentation used by Prototype](http://www.prototypejs.org/api/). I think we should shamelessly steal from them.
  69
+
  70
+## Real world examples
  71
+
  72
+We need some real projects to write documentation using SassDoc syntax and let us know what works, what doesn't, and what's missing.
  73
+
  74
+# Contributing
  75
+
  76
+Fork the main project and check in a change to the TODO file that indicates what you are working on.

0 notes on commit 63e4df6

Please sign in to comment.
Something went wrong with that request. Please try again.