search

adobe / hyde

A front-end to Jekyll that parses C++ sources to produce and enforce out-of-line documentation
http://opensource.adobe.com/hyde/
MIT License
323 stars 41 forks source link

use hyde as a clang-doc generator #68

Open pixxon opened 3 years ago

pixxon commented 3 years ago

Hi!

A friend of mine recommended this tool and I would like to use it on my libraries. I really like the output format, easy to read and easy to document. My only issue is integrating the tool itself into my build systems and pipelines. My main idea was to use the compile_commands.json provided by cmake, but it seems this tool is not ready to accept multiple translation units.

Is your feature request related to a problem? Please describe. This tool aims to provide documentation based on clang ast. There is already a similar tool in the llvm environment itself, called clang-doc. Would it be possible to merge the efforts of this project into that one?

Describe the solution you'd like In my opinion the easiest solution would be to merge this repository into the clang-doc as a generator format. This would require minimal modification in the clang-doc itself, but would require acceptance.

Describe alternatives you've considered Another option would be to extend clang-doc to accept external formatters, such as hyde. This would require modification in the clang-doc as right now it is not ready for that. Would also require modification in the hyde code base, but it would be very similar to the other approach. ( Fit to the Generator interface. )

Additional context One option would be to support multiple translation units via Executor, but it would cause duplicate effort because clang-doc already does this.

mnesarco commented 1 year ago

Hi @pixxon I am working on a clang-doc based tool that generates a rich relational model in an sqlite3 database file. From there, any tool can be used to generate documentation, by default I have a jinja2 template set. My tool is very experimental at this point, but tell me if it sounds interesting to you, if enough people is interested I will publish it. I have patched clang-doc a little but I have not submitted patches to mainstream yet as this is basically an experiment at this point.

My current approach is the following:

image

The benefit of having all the model in an sqlite3 database is that it can be used with any technology/lang to run analysis or generate code or documentation. It is also very portable, and of course it supports SQL queries, views, etc..