search

less / less-docs

Documentation for Less.
http://lesscss.org
Other
674 stars 446 forks source link

Documentation API #3

Open matthew-dean opened 11 years ago

matthew-dean commented 11 years ago

Are we planning to have an API for individual pieces of documentation? (So that someone can, say, look up a function in an editor?) ;-)

jonschlinkert commented 11 years ago

That sounds pretty interesting.

GitHub's API already allows pulling down blobs and readme's for instance, maybe wiki stuff, I'm not sure what other info, I'll have to see based on the specifics of what you're thinking. How do you envision this working, can you give me something in user-story form maybe?

matthew-dean commented 11 years ago

User right-click's on the word fadein. In the context menu, they have something like "Help for fadein()". It opens a help page with just that info, styled like the local app.

jonschlinkert commented 11 years ago

I love the idea, but I'm not sure that an API is the best way to do this. Seems like the spec would just need to be available as structured data, JSON/YAML (which I already started ;-), then whoever wanted to use the data could present it with whatever design they wanted. It would be such a small file that it could just be packaged up with other code or preferably just made available for anyone that wants to include it in their app. If you recall me saying that I was going to try to put the docs into JSON so they could be reused anywhere, this specifically wasn't on my mind, but it will definitely be enabled because of that I think.

Or is there another advantage of having an API do it?

matthew-dean commented 11 years ago

Sure sure, wouldn't have to be an API call, just structured in bits of downloadable segments.

jonschlinkert commented 11 years ago

K, I'm going to reopen though just to remind me that you requested this while I work on the data

russkel commented 11 years ago

If the documentation is written in something like ReST you can compile the documentation to various formats.