NEEDS example of "opinionated formatting template"... about dox HOT 32 CLOSED

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

from dox.

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.

from dox.

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.

from dox.

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.

from dox.

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

from dox.

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.

from dox.

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

from dox.

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.

from dox.

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

from dox.

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

from dox.

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.

from dox.

codex looks slick

from dox.

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

from dox.

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

from dox.

@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

from dox.

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

from dox.

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 :(

from dox.

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 <
[email protected]

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)

from dox.

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

from dox.

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

from dox.

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 <
[email protected]

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)

from dox.

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

from dox.

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

from dox.

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/

from dox.

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.

from dox.

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

from dox.

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

from dox.

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

from dox.

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

from dox.

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.

from dox.

Why is this issue closed??!!

from dox.

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.

from dox.