5 ms·

Daux.io, a simple documentation generator

107 points by bpierre 13y ago

ronaldsvilcins 13y ago
Nice!
slajax 13y 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.
- justinwars 13y 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 13y ago
Feedback: If I click the middle mouse button on the documentation here http://daux.io/Getting_Started 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 13y 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.
  - justinwars 13y ago
    I have heard some people having issues with horizontal scrolling, I am still trying to get to the bottom of this.
robinduckett 13y ago
Why does this need PHP?
- Wilya 13y ago
  Because it's written in PHP ?
  - IanCal 13y ago
    It's documentation. Why is it not static?
    - ben336 13y ago
      Its generating static files from MD files. That requires a server-side language of some type. The weird part is that it appears to use both Node and PHP.
  - michaelmior 13y ago
    Then why does it also need Grunt.js?
bhauer 13y 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.
- justinwars 13y ago
  Thanks! We will be pushing a fix for the scrollbar issue.
nwh 13y ago
Please kill the orphans in the "features" section — http://i.imgur.com/mbJ5bX8.png http://i.imgur.com/mbJ5bX8.png
deleted 13y ago
[deleted]
slajax 13y ago
I'd like to see this combined with swagger: https://developers.helloreverb.com/swagger/ https://developers.helloreverb.com/swagger/
- justinwars 13y 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 https://github.com/justinwalsh/daux.io/issues/13
mholt 13y 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.
- justinwars 13y 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 13y 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 13y 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.
  - exceptione 13y 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.
    - justinwars 13y ago
      The forced .md and underscores was mostly for speed of development on the first version of Daux. I agree it is a bit arbitrary and I plan on making the requirements a bit less strict in the future.
sciurus 13y ago
The feature "No Build Step" translates to "require your webserver to run PHP to render your documentation every time it's accessed".
- justinwars 13y 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 https://github.com/justinwalsh/daux.io/issues/6
exceptione 13y ago
I like the looks. My suggestion would be to distribute it as a single phar-archive (and to allow for hyphens).
ciokan 13y ago
https://github.com/justinwalsh/daux.io/blob/master/index.php 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 13y 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 https://news.ycombinator.com/item?id=3821125
- justinwars 13y 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 13y ago
with no mousewheel you have problems to scroll. Using the scrollbar is made impossible by overlapping … : (
fernly 13y 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 13y ago
There's also flatdoc http://ricostacruz.com/flatdoc/ http://ricostacruz.com/flatdoc/ which renders the markdown file on the client side ('marked' js parser), so no server-side stuff is needed.

107 points by bpierre 13y ago

Nice!

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.

justinwars 13y 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 13y ago

Feedback: If I click the middle mouse button on the documentation here http://daux.io/Getting_Started 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 13y 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.
- justinwars 13y ago
  I have heard some people having issues with horizontal scrolling, I am still trying to get to the bottom of this.

robinduckett 13y ago

Why does this need PHP?

Wilya 13y ago
Because it's written in PHP ?
- IanCal 13y ago
  It's documentation. Why is it not static?
  - ben336 13y ago
    Its generating static files from MD files. That requires a server-side language of some type. The weird part is that it appears to use both Node and PHP.
- michaelmior 13y ago
  Then why does it also need Grunt.js?

bhauer 13y 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.

justinwars 13y ago
Thanks! We will be pushing a fix for the scrollbar issue.

nwh 13y ago

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

deleted 13y ago

[deleted]

slajax 13y ago

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

justinwars 13y 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 https://github.com/justinwalsh/daux.io/issues/13

mholt 13y 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.

justinwars 13y 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 13y 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 13y 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.
- exceptione 13y 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.
  - justinwars 13y ago
    The forced .md and underscores was mostly for speed of development on the first version of Daux. I agree it is a bit arbitrary and I plan on making the requirements a bit less strict in the future.

sciurus 13y ago

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

justinwars 13y 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 https://github.com/justinwalsh/daux.io/issues/6

exceptione 13y ago

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

ciokan 13y ago

https://github.com/justinwalsh/daux.io/blob/master/index.php 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 13y 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 https://news.ycombinator.com/item?id=3821125
justinwars 13y 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 13y ago

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

fernly 13y 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 13y ago

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