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

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

Projects

None yet
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

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

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.

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.

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.

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

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.

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 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.

@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 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.

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.

Owner
tj commented Feb 10, 2012

codex looks slick

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

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

@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 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 :)

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 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:
#38 (comment)

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

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 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:
#38 (comment)

@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.

Contributor

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

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

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

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

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 commented Nov 24, 2012

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

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 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.

@ChiperSoft ChiperSoft closed this Mar 18, 2015
q2dg commented Mar 18, 2015

Why is this issue closed??!!

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.

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