The LibreOffice build system (gbuild) can be found in ./solenv/gbuild, it would be great to have up-to-date information on how to use it generated from inline comments in the makefile with doxygen. In fact there was an early attempt at this. It can be found in ./solenv/docs/gbuild. Its rather outdated nowadays. The objective of this Easy Hack is to: 1/ take whatever info is still relevant and valid from ./solenv/docs and add it as inline comments directly at solenv/gbuild. Delete ./solenv/docs when done. 2/ Create tooling (e.g. in Python) that extracts the "classes" and inline comments from the Makefiles in ./solenv/gbuild and creates something that doxygen can parse (e.g. roughly something as currently found in ./solenv/docs) 3/ Tweak this into our doxygen generation, so that they show up at http://docs.libreoffice.org/solenv/html/index.html, when the scripting is updated. Creating a doxygen config for this in ./solenv/doxygen.cfg show allow that.
Depending upon what your goal is, it's not necessary to create custom tooling or such. Simply configuring Doxygen to treat Make files as one of the scripting languages it supports will enable it to parse embedded documentation. Of the choices, I've found TCL is a better fit than Python, as with the latter, Doxygen picks up Make variables automatically, but can get some of it kind of wrong. I infer from looking at the existing documentation samples that the goal is to document only some of the content (specific targets and variables, not everything), in which case it's simplest to just manually type out the desired information at the start of the files. (If on the other hand the goal is actually to have something automatically parse GNU Make file syntax, it would probably make more sense to start a side project to add that functionality to Doxygen itself, rather than maintaining something custom just for LibreOffice.) I've attached sample Make and configuration files that demonstrate this approach. They're based upon the existing files in the LibreOffice source. (I haven't updated the sample's documentation to reflect current reality, just copied from the old fake C++ file in question, to demonstrate general feasibility.) This method requires manual application of tags to convey the desired structure, but still requires less typing than the original approach, I think. This is of course the easy part. The more time-consuming effort will be in actually documenting the Make files! Anyway, my two cents.
Created attachment 120630 [details] Sample Make file with embedded documentation
Created attachment 120631 [details] Sample customized Doxygen config file
Migrating Whiteboard tags to Keywords: (easyHack difficultyBeginner skillScript topicCleanup) [NinjaEdit]
JanI is default CC for Easy Hacks (Add Jan; remove LibreOffice Dev List from CC) [NinjaEdit]
(In reply to Björn Michaelsen from comment #0) Just to make sure, Do we want to have inline comments in the same *.mk file and a script to extract those comments and then parse it to doxygen ? But I guess it would make .mk files more verbose, since we have to stop parsing of commands. I tried to work with it and found that makefile rules/template codes need to be encapsulated like: ## @cond $(call gb_HelpTarget_HelpTarget,$(3),$(1),$(2)) $(call gb_HelpTarget_set_helpdir,$(3),$(gb_AllLangHelp_HELPDIR)) ## @endcond The above have to be done with every piece of code which needs to be encapsulated to prevent errors. Also, As David mentioned "I infer from looking at the existing documentation samples that the goal is to document only some of the content (specific targets and variables, not everything), in which case it's simplest to just manually type out the desired information at the start of the files." If David is right please let me know, I would just add the desired information. Since adding support to .mk files might be what doxygen group might be working on.
Created attachment 131521 [details] html_view_of_implmentation
Created attachment 131522 [details] html_details_of_class
Created attachment 131523 [details] html_view_of_implmentation
Hi Michaelsen, I have started to implement the concept mentioned by David and have attached few screenshot of how the implementation would look like. Can I continue in the same direction or is there any better way you could suggest about ?
A polite ping, still working on this bug
(In reply to jani from comment #11) > A polite ping, still working on this bug Reverting status to NEW, due to other engagement.
Discussed with Jan-Marek and closing. Comment "There is effectively no documentation to convert, because it's so outdated, it would just confuse more people."