Bug 91387 - create doxygen docs for the LibreOffice build system from inline comments
Summary: create doxygen docs for the LibreOffice build system from inline comments
Status: NEW
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: LibreOffice (show other bugs)
Version:
(earliest affected)
unspecified
Hardware: Other All
: medium normal
Assignee: Not Assigned
URL:
Whiteboard:
Keywords: difficultyBeginner, easyHack, skillScript, topicCleanup
Depends on:
Blocks: Build
  Show dependency treegraph
 
Reported: 2015-05-19 12:46 UTC by Björn Michaelsen
Modified: 2018-09-22 22:02 UTC (History)
5 users (show)

See Also:
Crash report or crash signature:


Attachments
Sample Make file with embedded documentation (3.66 KB, text/x-makefile)
2015-11-18 16:33 UTC, David H. Gutteridge
Details
Sample customized Doxygen config file (100.64 KB, text/plain)
2015-11-18 16:33 UTC, David H. Gutteridge
Details
html_view_of_implmentation (129.87 KB, image/png)
2017-02-28 07:06 UTC, Fakabbir amin
Details
html_details_of_class (108.62 KB, image/png)
2017-02-28 07:07 UTC, Fakabbir amin
Details
html_view_of_implmentation (129.87 KB, image/png)
2017-02-28 07:09 UTC, Fakabbir amin
Details

Note You need to log in before you can comment on or make changes to this bug.
Description Björn Michaelsen 2015-05-19 12:46:18 UTC
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.
Comment 1 David H. Gutteridge 2015-11-18 16:32:19 UTC
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.
Comment 2 David H. Gutteridge 2015-11-18 16:33:24 UTC
Created attachment 120630 [details]
Sample Make file with embedded documentation
Comment 3 David H. Gutteridge 2015-11-18 16:33:54 UTC
Created attachment 120631 [details]
Sample customized Doxygen config file
Comment 4 Robinson Tryon (qubit) 2015-12-14 06:53:54 UTC Comment hidden (obsolete)
Comment 5 Robinson Tryon (qubit) 2016-02-18 14:51:31 UTC Comment hidden (obsolete)
Comment 6 Fakabbir amin 2017-02-03 11:13:47 UTC
(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.
Comment 7 Fakabbir amin 2017-02-28 07:06:21 UTC
Created attachment 131521 [details]
html_view_of_implmentation
Comment 8 Fakabbir amin 2017-02-28 07:07:58 UTC
Created attachment 131522 [details]
html_details_of_class
Comment 9 Fakabbir amin 2017-02-28 07:09:44 UTC
Created attachment 131523 [details]
html_view_of_implmentation
Comment 10 Fakabbir amin 2017-02-28 07:15:08 UTC
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 ?
Comment 11 jani 2017-05-14 07:42:29 UTC Comment hidden (obsolete)
Comment 12 Fakabbir amin 2017-05-14 11:40:41 UTC
(In reply to jani from comment #11)
> A polite ping, still working on this bug

Reverting status to NEW, due to other engagement.