Exploring documentation

uncovering hidden gems

Scrolls, CC by-nc 2.0 Hc_07, from https://www.flickr.com/photos/82684220@N00/449833847/

As much as I always disliked the need to restart a server after changing a value in portal-ext.properties, I still love the fact that - for years - the available reference of possible options has been there and grew to 12379 lines at the time of this writing. It containing value keys, defaults, possible other values and documentation. And the fact that those are more than 12000 lines is somewhat funny, because since 2016 the plan is to move more and more to OSGi-based configuration that doesn't require a restart. I didn't check the stats on portal.properties, but it feels like it still grew considerably since I looked last time.

Anyway... I love that there is a common reference, that contains documentation, and is a good place to look up possible values.

With the move to OSGi configuration, we now save us a minute to restart the server after changing the configuration, at the price of missing out on a central directory of possible values. The Ctrl-F based lookup in portal.properties is always amazingly fast - and precisely on the version that I need the result in.

That's where a colleague of mine nerd-sniped me last week and asked "Do we have a central place of documentation for all available OSGi configs?". Well, Ladies and Gentlepeople, my answer last week was: "it doesn't exist". Today it's: "Check this out". There's a github repository with ugly exploration-style code, generating ugly output (yes, it's using <table> and minimal styling to motivate someone to make it pretty) that does the job.

I've only tried it on DXP 7.3, but assume that it wouldn't require changes for any other 7.x version. If you don't want to try it, but just want to see the result: Here it is.

If you want to run it yourself (to document all of the configuration available on your system), make it more complete, generate content for other languages, or prettify it: Here's the code.

Vote for LRDOCS-9384 to make this part of standard documentation. And install ControlPanelDocumentation (more info here) for even more docs.

And here's a small sample of the current 400kB documentation, as screenshot to show the original <table> glory ;)


 

(Illustration: Scrolls, CC by-nc 2.0 Hc_07)