Hacker News Reader

Comment by mempko | Hacker News Reader

Question, any live examples?

Live? Even offline examples would be great. The description is painfully laconic and it's really hard to guess what exactly is generated. Which is a shame, because the project looks like a rather nice solution to really common problem

If the repository README isn't clear, please let me know what more you would like to see there. From that document:

> hyde does not produce pretty-printed output. Rather, it produces well structured Markdown files that contain YAML front-matter. These files can then be consumed by other tools (like Jekyll) to customize the structure and layout of the final documentation.

Well you don't have any examples of the documentation that is produced. Our even of how you actually write the documentation.

To me the readme and examples you've linked read like:

1. You write normal code with no inline documentation, and no links to external documentation.

2. You run it through a tool with produces JSON. And feed that into a static sure generator.

3. Your code is now magically documented. Somehow.

I have no idea where the actual documentation is...

A sample of the kind of documentation it can produce is here: http://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_w...

Ah this looks nice! Would be helpful to know how you go from hyde output to this result and where it gets "notes" from.

Ok this should be the first link in the readme.

Generally sibling comment by IshKebab lists most of the things that were not clear for me. The biggest point, however, is that I wasn't able to get clear picture of what is considered here to be the "documentation". I get what file format is generated, but I have no idea what will be the content and how it will be inferred from my code.

> please let me know what more you would like to see there

I would love to see Hyde dogfood Hyde. I think that might be helpful to those coming in to check it out. What does the documentation of Hyde look like put through Hyde and output through vanilla Jekyll?

Clever name, by the way.

We are in the process of updating/migrating the docs at http://stlab.cc over to hyde. GitHub is being slow today, so the site changes aren't live yet. However, you can view the sources (what hyde actually outputs) here: https://github.com/stlab/stlab.github.io/tree/master/librari... . Any file within there was created by the tool (for example: https://raw.githubusercontent.com/stlab/stlab.github.io/mast...)

The above documentation is derived from the following source file: https://github.com/stlab/libraries/blob/develop/stlab/copy_o...

I am genuinely curious what's out-of-line mean here, especially comparing with Doxygen. Doxygen can generate xml output, and these xml output are easy to parse to either generate markdown, or rst, and then feeding to to Jekyll or Sphinx.

Reply on news.ycombinator.com