Daux.io, a simple documentation generator

http://daux.io

by bpierre • 13 years ago

107 31 13 years ago

daux.io

ronaldsvilcins• 13 years ago

Nice!

slajax2• 13 years ago

I used something very similar a few years ago. I think it was called dox.js.

Whats the story on the super similar name and ui? Is it the same thing? I'm not trolling, I'm curious if they are related cause it was a great doc system IMO.

justinwars8• 13 years ago

Wow, we even looked around when naming Daux to make sure there wouldn't be any conflicts. I took a look at the dox project and I think we are going to be ok. It looks to be a significantly different approach.

sergiotapia• 13 years ago

Feedback: If I click the middle mouse button on the documentation here http://daux.io/Getting_Started I get the scroller icon thingy appear. Then I can scroll by moving the mouse right or left and make the content dissapear at which point I go far enough and it bounces back.

This _exact_ same effect happens on Outlook.com if you want to take a look at reproducing it there as well.

pests• 13 years ago

It appears there is more content to the right and you are simply scrolling the page (moving the view opposite to direction of mouse movement) and once you hit the edge it seems to invalidate the drag or something similar.

This is just from playing with it; I haven't had time to check the source yet.

justinwars8• 13 years ago

I have heard some people having issues with horizontal scrolling, I am still trying to get to the bottom of this.

robinduckett• 13 years ago

Why does this need PHP?

Wilya• 13 years ago

Because it's written in PHP ?

IanCal• 13 years ago

It's documentation. Why is it not static?

michaelmior• 13 years ago

Then why does it also need Grunt.js?

bhauer• 13 years ago

This is very nice. Well done! I especially like the clean default styles.

One minor nit: the "fork me on Github" is superimposed over the scrolling pane, so it's not possible to grab the scroll tack. That is, I can only scroll via my mousewheel until the tack is past the fork overlay.

justinwars8• 13 years ago

Thanks! We will be pushing a fix for the scrollbar issue.

nwh• 13 years ago

Please kill the orphans in the "features" section — http://i.imgur.com/mbJ5bX8.png

slajax2• 13 years ago

I'd like to see this combined with swagger: https://developers.helloreverb.com/swagger/

justinwars8• 13 years ago

Interesting idea. I will look into what some possible options are. In the mean time I create a Github issue to track the request: https://github.com/justinwalsh/daux.io/issues/13

mholt• 13 years ago

Way cool. Not sure I'm a fan of the syntax-highlighted code snippets to the right and in black text on the dark blue background though. Might like to see it closer to the content, and with more contrast.

justinwars8• 13 years ago

If your not a fan of the code floating, that can be disabled. We are working on getting some better code styles as well that should fix the contrast issue.

RyanZAG• 13 years ago

"You must use the .md file extension for your files. Also, you must use underscores instead of spaces."

Why? Are we still using MSDOS or something?

martin-adams• 13 years ago

There's probably no technical reason why other than design choice. It may be related to cleaner URLs omitting the %20 encoding.

However, hyphens would probably have been a better choice for URLs as Google treats them as individual words as opposed to one long keyword.

exceptione2• 13 years ago

Also, hyphens save us an additional <shift>-key press. Hardly on topic, but my advise is to require underscores only when there is absolutely no alternative. Which is almost never the case.

sciurus• 13 years ago

The feature "No Build Step" translates to "require your webserver to run PHP to render your documentation every time it's accessed".

justinwars8• 13 years ago

This is completely true, and I started a Github issue to create an optional build script to generate a static set of files that could be deployed to S3, Github Pages or something similar. https://github.com/justinwalsh/daux.io/issues/6

exceptione2• 13 years ago

I like the looks. My suggestion would be to distribute it as a single phar-archive (and to allow for hyphens).

ciokan• 13 years ago

https://github.com/justinwalsh/daux.io/blob/master/index.php Seriously. Pick a template engine at least. They're around for quite some time.

PHP & Node? Pick one. Don't make it a pain to even install.

gramsey• 13 years ago

PHP
Pick a template engine at least.

There's a great one for PHP, it's called PHP. https://news.ycombinator.com/item?id=3821125

justinwars8• 13 years ago

I agree I should have used a template engine. I wrote most of this with the idea that it would be a proof of concept but ended up turning into something I felt others would still benefit from. It's still simple enough to get around the code without a template engine, but I would love to refactor one in.

akldjlafkjalfk• 13 years ago

with no mousewheel you have problems to scroll. Using the scrollbar is made impossible by overlapping … : (

fernly• 13 years ago

I suppose "daux" is meant to be pronounced "docks" but a French-speaker would say "doh!" like Homer Simpson.

Trivia aside, the front page does nothing to make the purpose or advantages clear. What is "custom documentation"? (Is there another kind?) What is the advantage of "on the fly"? (As opposed to the typical "make doc".)

Is there some way to create a multi-level hierarchy within the "01_Getting_Started.md" filename convention? Is the filename structure the _only_ way to indicate structure? (If so, a trivial structure change turns into a nontrivial exercise of renaming files and getting git or svn to accept renamed files as logically unchanged.) Is there a way to cross-reference (link) between files? Is there a way to output in PDF, or any other format?

sohooo• 13 years ago

There's also flatdoc http://ricostacruz.com/flatdoc/ which renders the markdown file on the client side ('marked' js parser), so no server-side stuff is needed.

Daux.io, a simple documentation generator

Related Stories