zeal
zeal copied to clipboard
zealdocs
Add support for Ruby documentation
Zeal should support direct docset generation from RDoc and Yard formats.
This feature has been requested several times, see #63 and #170.
I'd be happy to work on this when I have time, but is there a format specification or something I can reference?
I am not sure yet what would be the best way to approach this. Generating docsets in Dash format from RDoc markup doesn't sound reasonable to me.
I have an idea of another Zeal specific format, that would store information about symbols (classes, methods, articles) instead of markup. Then Zeal could render such documentation in any way. That would also simplify creation of generators for other documentation formats like Javadoc or Doxygen. A unified approach to all different generated docs sounds appealing.
I am open to discussion.
:+1:
I think this endeavour might involve getting the documentation generator to spit out the documentation in some machine-readable format (Yard supports YAML) then importing that instead.
That would require us to write stylesheets and stuff for styling the documentation, however.
Would other documentation sources be troublesome, though? We are currently assuming we have source access to generate the documentation in the first place. What if the documentation is already in some other format?
Generating documentation from annotated sources is the best situation. Using other interim formats or not is a technical question, though bundling different generators with Zeal is not a good idea. Another option would be to provide a server-side service for docset generation, but that would raise financial questions.
Regarding other formats, I have long term plans to add a native support for QCH, CHM, PDF and Man pages. Perhaps, something else as well. We could also come up with scrapers for generated docs, to build docsets from HTML pages the way Dash and DevDocs developers do.
The main problem I see is the generation of index. Documentation formats I am aware of lack any information about symbol types. Docsets without such information wouldn't be comfortable to use or good looking.
And now?
Pretty important feature.
Would it be hard to generate in Dash format, to begin with? I read that Dash uses a program in Objective-C to do it. If I can help in any way, I would be happy to, even though my knowledge of C++ is pretty limited.
Yes, what steps are involved in adding this kind of support? I'd be interested in helping out on this because I would love this feature, but I don't have the time to learn Objective-C plus figure out the project architecture etc. But maybe RubyGems can do most of the work and we can just point Dash in the right direction.
Just wondering, can we use this tool meanwhile as a bridge? https://github.com/yasslab/docset Or would that also produce a format that is incompatible with zeal?
I have seen that there is this bash script https://gist.github.com/toch/77ce4210e962cb73782d003a89f17dcd
I was able to get it running but afterwards I was not able to find any docsets on my machine...
