NEEDS example of "opinionated formatting template"... #38

Closed
ddopson opened this Issue Nov 7, 2011 · 32 comments

Comments

Projects
None yet
@ddopson

ddopson commented Nov 7, 2011

See the discussion on this StackOverflow posting:
http://stackoverflow.com/questions/6096649/documenting-node-js-projects/6995688#6995688

Basically, mere mortals are intimidated by the task of creating a template to turn pure "unopinionated" JSON code structure metadata into human consumable "opinionated" HTML. The concept of factoring apart the parser from the formatter is great; we just need an example of how a template would work.... a starting point. Adding this (plus a mention in the README.md) would go a long way towards making this module consumable by others.

As much as I'd love to do the work myself and submit a "pull request", honestly, I'm not entirely sure how to create such a template either. Not that I'd ever admit that... ;)

Cheers,
--- Dave

@tj

This comment has been minimized.

Show comment Hide comment
@tj

tj Nov 7, 2011

Owner

yup! I plan on adding reference to one when I have the time. the --debug option will show you the json created so you can reference that as you iterate through with a template etc, but yeah examples would be nice

Owner

tj commented Nov 7, 2011

yup! I plan on adding reference to one when I have the time. the --debug option will show you the json created so you can reference that as you iterate through with a template etc, but yeah examples would be nice

@olivernn

This comment has been minimized.

Show comment Hide comment
@olivernn

olivernn Nov 8, 2011

Contributor

It is far from perfect but I have created a template to convert the raw json output from dox into some html. The results can be seen here - http://olivernn.github.com/davis.js/docs/ and the code is in the repository here https://github.com/olivernn/davis.js/tree/master/docs.

It could potentially be used as a starting point for some kind of template - it woult need a tidy though.

Contributor

olivernn commented Nov 8, 2011

It is far from perfect but I have created a template to convert the raw json output from dox into some html. The results can be seen here - http://olivernn.github.com/davis.js/docs/ and the code is in the repository here https://github.com/olivernn/davis.js/tree/master/docs.

It could potentially be used as a starting point for some kind of template - it woult need a tidy though.

@olivernn

This comment has been minimized.

Show comment Hide comment
@olivernn

olivernn Nov 8, 2011

Contributor

Just had a look through my templating - it is using my fork of dox because I wanted to add support for some extra jsdoc tags. I haven't had a chance to put this together into a pull request but will try and get round to doing that this week-ish.

Contributor

olivernn commented Nov 8, 2011

Just had a look through my templating - it is using my fork of dox because I wanted to add support for some extra jsdoc tags. I haven't had a chance to put this together into a pull request but will try and get round to doing that this week-ish.

@aslakhellesoy

This comment has been minimized.

Show comment Hide comment
@aslakhellesoy

aslakhellesoy Feb 10, 2012

I'm also curious about this. Apart from @olivernn I haven't found any projects on github that actually use dox, not even @visionmedia's own projects.

I'm also curious about this. Apart from @olivernn I haven't found any projects on github that actually use dox, not even @visionmedia's own projects.

@tj

This comment has been minimized.

Show comment Hide comment
@tj

tj Feb 10, 2012

Owner

I almost always choose to go with hand-written docs if the projects are importantant at all. Quite frankly I think clean source is the best reference documentation you can find, unfortunately most people are used to nasty source so they dont think to look or something

Owner

tj commented Feb 10, 2012

I almost always choose to go with hand-written docs if the projects are importantant at all. Quite frankly I think clean source is the best reference documentation you can find, unfortunately most people are used to nasty source so they dont think to look or something

@olivernn

This comment has been minimized.

Show comment Hide comment
@olivernn

olivernn Feb 10, 2012

Contributor

I am using dox to build docs because I like to have documentation inline with the source. I'm far more likely to keep documentation up to date if it is right next to methods that I'm changing.

Contributor

olivernn commented Feb 10, 2012

I am using dox to build docs because I like to have documentation inline with the source. I'm far more likely to keep documentation up to date if it is right next to methods that I'm changing.

@tj

This comment has been minimized.

Show comment Hide comment
@tj

tj Feb 10, 2012

Owner

yeah same here, it's dumb not to have some form of documentation in-source anyway so it's a win-win in general but sometimes it's just easier to copy/paste and generate some manual markdown docs

Owner

tj commented Feb 10, 2012

yeah same here, it's dumb not to have some form of documentation in-source anyway so it's a win-win in general but sometimes it's just easier to copy/paste and generate some manual markdown docs

@itay

This comment has been minimized.

Show comment Hide comment
@itay

itay Feb 10, 2012

We use it for the Splunk JS SDK, with a modified version of dox and a modified version @olivernn's template.

You can see the generated docs here:
http://splunk.github.com/splunk-sdk-javascript/docs/0.1.0/index.html

And the modified code:
https://github.com/splunk/splunk-sdk-javascript/tree/master/contrib/dox

Let me know if you have any questions.

itay commented Feb 10, 2012

We use it for the Splunk JS SDK, with a modified version of dox and a modified version @olivernn's template.

You can see the generated docs here:
http://splunk.github.com/splunk-sdk-javascript/docs/0.1.0/index.html

And the modified code:
https://github.com/splunk/splunk-sdk-javascript/tree/master/contrib/dox

Let me know if you have any questions.

@aslakhellesoy

This comment has been minimized.

Show comment Hide comment
@aslakhellesoy

aslakhellesoy Feb 10, 2012

@itay nice! Is couldn't get search to work (nothing happens) and the console says Uncaught ReferenceError: raw is not defined.

Otherwise - looks like a good starting point.

@itay nice! Is couldn't get search to work (nothing happens) and the console says Uncaught ReferenceError: raw is not defined.

Otherwise - looks like a good starting point.

@itay

This comment has been minimized.

Show comment Hide comment
@itay

itay Feb 10, 2012

@aslakhellesoy I'm pretty sure I disabled it by accident because the JSON representation of the data (which powers search) is massive, so I removed it, not realizing it broke search :)

Let me know if you need any clarifications. Some of my changes are pretty specific to what I needed, but I can help work around them. All props go to @olivernn for making the template in the first place.

itay commented Feb 10, 2012

@aslakhellesoy I'm pretty sure I disabled it by accident because the JSON representation of the data (which powers search) is massive, so I removed it, not realizing it broke search :)

Let me know if you need any clarifications. Some of my changes are pretty specific to what I needed, but I can help work around them. All props go to @olivernn for making the template in the first place.

@logicalparadox

This comment has been minimized.

Show comment Hide comment
@logicalparadox

logicalparadox Feb 10, 2012

Contributor

My codex static-site generator includes a code plugin that uses dox parsed code as a supplement to the plain markdown based guide. I use this for a number of my project sites, but chai is the most involved. The template and config are available here.

Questions always welcome.

Contributor

logicalparadox commented Feb 10, 2012

My codex static-site generator includes a code plugin that uses dox parsed code as a supplement to the plain markdown based guide. I use this for a number of my project sites, but chai is the most involved. The template and config are available here.

Questions always welcome.

@tj

This comment has been minimized.

Show comment Hide comment
@tj

tj Feb 10, 2012

Owner

codex looks slick

Owner

tj commented Feb 10, 2012

codex looks slick

@tj

This comment has been minimized.

Show comment Hide comment
@tj

tj Feb 10, 2012

Owner

i need to use something for superagent haha, like @olivernn said it's easier to maintain the stuff in source, I haven't updated the docs in quite a while

Owner

tj commented Feb 10, 2012

i need to use something for superagent haha, like @olivernn said it's easier to maintain the stuff in source, I haven't updated the docs in quite a while

@logicalparadox

This comment has been minimized.

Show comment Hide comment
@logicalparadox

logicalparadox Feb 10, 2012

Contributor

@visionmedia Thanks! If you end up using codex, let me know. Ironically, it lacks documentation at the moment but I hope to get to that soon.

Contributor

logicalparadox commented Feb 10, 2012

@visionmedia Thanks! If you end up using codex, let me know. Ironically, it lacks documentation at the moment but I hope to get to that soon.

@olivernn

This comment has been minimized.

Show comment Hide comment
@olivernn

olivernn Feb 10, 2012

Contributor

@itay good to see the template being used! I'll try this weekend to at least put the source up on github so there is a place for it, feel free to then open pull requests with your changes.

The search should be able to handle quite a large amount of data, if there are specific problems let me know cos it is powered by a library that I'm currently working on, currently its a work in progress but is here

Contributor

olivernn commented Feb 10, 2012

@itay good to see the template being used! I'll try this weekend to at least put the source up on github so there is a place for it, feel free to then open pull requests with your changes.

The search should be able to handle quite a large amount of data, if there are specific problems let me know cos it is powered by a library that I'm currently working on, currently its a work in progress but is here

@itay

This comment has been minimized.

Show comment Hide comment
@itay

itay Feb 10, 2012

@olivernn the problem wasn't the search not being able to handle it - but just the mere size of the data. It was a huge block of JSON right at the beginning of the page, so the page loaded slower as well, etc. The search worked great :)

itay commented Feb 10, 2012

@olivernn the problem wasn't the search not being able to handle it - but just the mere size of the data. It was a huge block of JSON right at the beginning of the page, so the page loaded slower as well, etc. The search worked great :)

@tj

This comment has been minimized.

Show comment Hide comment
@tj

tj Feb 10, 2012

Owner

that's why I wanted to get dox away from some pre-defined template thing, it doesn't work for everyone, and the lame copy of docco styling I had looks like ass, when API references look worse than source on github it's not a good thing :(

Owner

tj commented Feb 10, 2012

that's why I wanted to get dox away from some pre-defined template thing, it doesn't work for everyone, and the lame copy of docco styling I had looks like ass, when API references look worse than source on github it's not a good thing :(

@itay

This comment has been minimized.

Show comment Hide comment
@itay

itay Feb 10, 2012

The one benefit of a default template is that it is a starting point, so
then people can make the modifications they need. Having to write one up
from scratch is not trivial.

I imagine you could probably use bootstrap to do something pretty nice
nowadays.

On Fri, Feb 10, 2012 at 2:13 PM, TJ Holowaychuk <
reply@reply.github.com

wrote:

that's why I wanted to get dox away from some pre-defined template thing,
it doesn't work for everyone, and the lame copy of docco styling I had
looks like ass, when API references look worse than source on github it's
not a good thing :(


Reply to this email directly or view it on GitHub:
visionmedia#38 (comment)

itay commented Feb 10, 2012

The one benefit of a default template is that it is a starting point, so
then people can make the modifications they need. Having to write one up
from scratch is not trivial.

I imagine you could probably use bootstrap to do something pretty nice
nowadays.

On Fri, Feb 10, 2012 at 2:13 PM, TJ Holowaychuk <
reply@reply.github.com

wrote:

that's why I wanted to get dox away from some pre-defined template thing,
it doesn't work for everyone, and the lame copy of docco styling I had
looks like ass, when API references look worse than source on github it's
not a good thing :(


Reply to this email directly or view it on GitHub:
visionmedia#38 (comment)

@tj

This comment has been minimized.

Show comment Hide comment
@tj

tj Feb 10, 2012

Owner

it's somewhat trivial, I mean web people write templates every day (usually), a few concrete examples would definitely help though

Owner

tj commented Feb 10, 2012

it's somewhat trivial, I mean web people write templates every day (usually), a few concrete examples would definitely help though

@tj

This comment has been minimized.

Show comment Hide comment
@tj

tj Feb 10, 2012

Owner

lately im just pointing to GH files haha, it's effectively the same thing I would want to display anyway

Owner

tj commented Feb 10, 2012

lately im just pointing to GH files haha, it's effectively the same thing I would want to display anyway

@itay

This comment has been minimized.

Show comment Hide comment
@itay

itay Feb 10, 2012

The main use for me has been when I have several files and I use the docs
as a central way to show the overview.

And you're right - spinning up a template isn't hard for web people, but
some of us are visually challenged (like me!) :)

On Fri, Feb 10, 2012 at 2:17 PM, TJ Holowaychuk <
reply@reply.github.com

wrote:

lately im just pointing to GH files haha, it's effectively the same thing
I would want to display anyway


Reply to this email directly or view it on GitHub:
visionmedia#38 (comment)

itay commented Feb 10, 2012

The main use for me has been when I have several files and I use the docs
as a central way to show the overview.

And you're right - spinning up a template isn't hard for web people, but
some of us are visually challenged (like me!) :)

On Fri, Feb 10, 2012 at 2:17 PM, TJ Holowaychuk <
reply@reply.github.com

wrote:

lately im just pointing to GH files haha, it's effectively the same thing
I would want to display anyway


Reply to this email directly or view it on GitHub:
visionmedia#38 (comment)

@aslakhellesoy

This comment has been minimized.

Show comment Hide comment
@aslakhellesoy

aslakhellesoy Feb 10, 2012

@visionmedia writing a template is trivial, but I don't think the JSON outputted by dox is trivial, hence the need for some kind of starter template that gives an example of how to consume the JSON.

@visionmedia writing a template is trivial, but I don't think the JSON outputted by dox is trivial, hence the need for some kind of starter template that gives an example of how to consume the JSON.

@olivernn

This comment has been minimized.

Show comment Hide comment
@olivernn

olivernn Feb 14, 2012

Contributor

I've put up my template code etc so it can be forked, fixed, whatever - https://github.com/olivernn/dox-template

Contributor

olivernn commented Feb 14, 2012

I've put up my template code etc so it can be forked, fixed, whatever - https://github.com/olivernn/dox-template

@logicalparadox

This comment has been minimized.

Show comment Hide comment
@logicalparadox

logicalparadox Feb 17, 2012

Contributor

I have release a template for Codex that shows how to use the dox integration. It has a lot of sane defaults and can easily be customized for fonts and colors using stylus variables. - https://github.com/logicalparadox/codex-hub/

Contributor

logicalparadox commented Feb 17, 2012

I have release a template for Codex that shows how to use the dox integration. It has a lot of sane defaults and can easily be customized for fonts and colors using stylus variables. - https://github.com/logicalparadox/codex-hub/

@olivernn

This comment has been minimized.

Show comment Hide comment
@olivernn

olivernn Mar 30, 2012

Contributor

Okay, I finally got around to wrapping up my template into a npm module, you can install it with npm install dox-template, any feedback is very welcome.

Contributor

olivernn commented Mar 30, 2012

Okay, I finally got around to wrapping up my template into a npm module, you can install it with npm install dox-template, any feedback is very welcome.

@ForbesLindesay

This comment has been minimized.

Show comment Hide comment
@ForbesLindesay

ForbesLindesay May 16, 2012

Contributor

I've also written my own sample template. The plan was to keep it as simple as possible (and I'm going to work on making it simpler) while not loosing information. It can produce both a markdown and an html output, and does syntax highlighting on code https://github.com/jepso/dox-basic

Contributor

ForbesLindesay commented May 16, 2012

I've also written my own sample template. The plan was to keep it as simple as possible (and I'm going to work on making it simpler) while not loosing information. It can produce both a markdown and an html output, and does syntax highlighting on code https://github.com/jepso/dox-basic

@mattmcmanus

This comment has been minimized.

Show comment Hide comment
@mattmcmanus

mattmcmanus Sep 23, 2012

I suppose I'll throw my hat in here as well. Inspired by @ForbesLindesay's dox-basic I made something similar:

https://github.com/punkave/dox-foundation

I suppose I'll throw my hat in here as well. Inspired by @ForbesLindesay's dox-basic I made something similar:

https://github.com/punkave/dox-foundation

@rump

This comment has been minimized.

Show comment Hide comment
@rump

rump Nov 24, 2012

Pushing into Markdown is a saweet idea also:
https://github.com/cbou/markdox

rump commented Nov 24, 2012

Pushing into Markdown is a saweet idea also:
https://github.com/cbou/markdox

@aearly

This comment has been minimized.

Show comment Hide comment
@aearly

aearly Dec 21, 2012

Here is my "opinionated template". Produces docco-like output, essentially becoming docco for block-style comments. Powered by dust.js, so you can plug in any dust template you want.

https://github.com/aearly/dox-docco

aearly commented Dec 21, 2012

Here is my "opinionated template". Produces docco-like output, essentially becoming docco for block-style comments. Powered by dust.js, so you can plug in any dust template you want.

https://github.com/aearly/dox-docco

@mwbrooks mwbrooks referenced this issue in phonegap/phonegap-cli Mar 22, 2013

Open

JavaScript API Documentation #16

@q2dg

This comment has been minimized.

Show comment Hide comment
@q2dg

q2dg Nov 19, 2014

Could be possible adding a section in Readme.md of Dox showing a list with those templates mentioned in this thread? It would be very useful to visitors and it could (partially) resolve original question of this issue, I think. Thanks.

q2dg commented Nov 19, 2014

Could be possible adding a section in Readme.md of Dox showing a list with those templates mentioned in this thread? It would be very useful to visitors and it could (partially) resolve original question of this issue, I think. Thanks.

@Twipped Twipped closed this Mar 18, 2015

@q2dg

This comment has been minimized.

Show comment Hide comment
@q2dg

q2dg Mar 18, 2015

Why is this issue closed??!!

q2dg commented Mar 18, 2015

Why is this issue closed??!!

@Twipped

This comment has been minimized.

Show comment Hide comment
@Twipped

Twipped Mar 18, 2015

Collaborator

It's a three and a half year old issue that I feel has been answered by the participants. There are many examples here of how to format dox output in various template languages.

If someone wants to make a PR to enhance the documentation with concrete examples, I'll merge it, but I don't agree that in 2015 people NEED to see an example template.

Collaborator

Twipped commented Mar 18, 2015

It's a three and a half year old issue that I feel has been answered by the participants. There are many examples here of how to format dox output in various template languages.

If someone wants to make a PR to enhance the documentation with concrete examples, I'll merge it, but I don't agree that in 2015 people NEED to see an example template.

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