DocBook Documentation Project

The migration of Adempiere modules to iDempiere

DocBook Documentation Project

Postby red1 » Thu Oct 02, 2014 7:01 pm

Hi community,
I have begun a documentation project based on the DocBook XML framework. The idea is to formulate helpful content in the form of XML that can be used later to generate target output formats such as HTML, PDF, ePUB and Windows Help book content. Basic information about using DocBook can be seen here http://www.vogella.com/tutorials/DocBook/article.html

I went a step further by making a DocBookGenerator that automatically traverse the whole Application Dictionary (AD) content to pull out its meta-data information into the DocBook.xml format. This idea is not unlike what Carlos Ruiz has done here http://www.adempiere.com/Manual (his first very powerful generated content during the founding days of the ADempiere project which he replicated also for iDempiere).
I have uploaded my generated sample here: http://red1.org/DocBook/

However the DocBook model generation is more versatile in two aspects:
1. Been DocBook.xml based it is not just output ready for HTML to be presented on Web browsers. It can also be rendered in the above mentioned view formats.
2. The data traversed is more elaborate where the underlying layers of meta-data is pulled out:
2.1. Reports' related View Tables are also automatically rendered
2.2 Where Reference is made to Lists, the lists' values are presented
2.3 Validation Rules and even Callouts are presented
2.4 Workflow complete framework of Node to Transition to Condition are laid out
2.5 More useful information for Windows/Tabs/Fields are presented

Below are screenshots of this work in progress. I am looking next at how the PDF formatting can be done best.
I also made a side code to generate a menu hyperplinker index to get to all the generated HTMLs. Later i will structure them just like what Carlos Ruiz did.
Source code is committed to http://idempiere.atlassian.net/browse/IDEMPIERE-2223

DocBookMenu.png
DocBookMenu.png (137.66 KiB) Viewed 15434 times
Here is the initial success from a generated DocBook.xml sample
DocBookSample.png
DocBookSample.png (84.02 KiB) Viewed 15434 times
Getting to the List's options is very useful for fast snap without clicking into the application
RefList.png
RefList.png (41.71 KiB) Viewed 15434 times
Reports has their underlying view tables presented at the same time
DocBookReport.png
DocBookReport.png (95.02 KiB) Viewed 15434 times
Callouts where exist are presented together in the Validation Rules column
DocBookCallout.png
DocBookCallout.png (64.63 KiB) Viewed 15434 times
You can now get a single picture snap of the Workflow's Nodes, Transitions and Conditions if any.
DocBookWF.png
DocBookWF.png (54.63 KiB) Viewed 15434 times
red1
Site Admin
 
Posts: 2760
Joined: Tue Jul 06, 2004 3:01 pm
Location: Kuala Lumpur, Malaysia

Re: DocBook Documentation Project

Postby collazosc » Sat Oct 04, 2014 8:13 pm

Great work. This is a must for the community.
---------------------------
Carlos Collazos
---------------------------
collazosc
 
Posts: 36
Joined: Thu Dec 29, 2011 9:35 am

Re: DocBook Documentation Project

Postby red1 » Tue Oct 07, 2014 2:22 am

Some latest improvements (viewable live at http://red1.org/DocBook/, code at http://idempiere.atlassian.net/browse/IDEMPIERE-2223) latest source at https://bitbucket.org/red1/docbookgenerator:
1. Created / Updated timestamps. This is something that i been thinking about on my own. How often has I as a developer or when debugging the Application Dictionary wanted to know since when such and such a table model was introduced into the ERP software? And was it updated? Of course if I can find out by who and under what tracker that be good. But for now the following screenshot is a big leap in that direction.

InfoBP.png
InfoBP.png (95.23 KiB) Viewed 15375 times
2. At the same time note also from above that the rest of the Menu items such as Forms and InfoPanel windows are now part of the fare.

3. There is also another constant question that comes to mind during the checking up of any model in the Window's Tabs i.e. what is the exact Database table name associated to each Tab? It is now conveniently always visible as seen below.

TableName.png
TableName.png (59.7 KiB) Viewed 15375 times
4. I also made the linkages page to be indexed so that you can see how many items are there and how many are for each category.

DocBookIndex.png
DocBookIndex.png (89.29 KiB) Viewed 15375 times
As you can see above, there are 283 Windows, 24 Forms and 8 Info Panels. All in 468 items exist or are marshaled within and by the Application Dictionary.

Next I will try to make hyperlink or lookup for each Java class encountered in the AD, which means you should be able to click on the classname to view at least the APIDOCs information.
red1
Site Admin
 
Posts: 2760
Joined: Tue Jul 06, 2004 3:01 pm
Location: Kuala Lumpur, Malaysia

Re: DocBook Documentation Project

Postby red1 » Sun Oct 12, 2014 1:21 am

I have now made both the images and Javadocs linkages to the respective items.

DocLinks.png
DocLinks.png (36.91 KiB) Viewed 15320 times
As seen on one item here, links are now present for both. Below is the Javadoc.

DocBookJavaDoc.png
DocBookJavaDoc.png (56.48 KiB) Viewed 15320 times
And here is the Image of the screen taken from the iDempiere wiki.

DocBookImage.png
DocBookImage.png (123.56 KiB) Viewed 15320 times
All this allows simple click thru to quickly find out all the AD information without bringing up iDempiere or accessing the PostgreSQL database.
red1
Site Admin
 
Posts: 2760
Joined: Tue Jul 06, 2004 3:01 pm
Location: Kuala Lumpur, Malaysia

Re: DocBook Documentation Project

Postby red1 » Sun Oct 12, 2014 1:52 pm

I made a YouTube movie on this one:
red1
Site Admin
 
Posts: 2760
Joined: Tue Jul 06, 2004 3:01 pm
Location: Kuala Lumpur, Malaysia

Re: DocBook Documentation Project

Postby red1 » Mon Oct 13, 2014 1:41 pm

Callouts are also linked to its Javadoc.

callout.png
callout.png (67.55 KiB) Viewed 15301 times
javadocCallout.png
javadocCallout.png (61.64 KiB) Viewed 15301 times
red1
Site Admin
 
Posts: 2760
Joined: Tue Jul 06, 2004 3:01 pm
Location: Kuala Lumpur, Malaysia

Re: DocBook Documentation Project

Postby red1 » Sun Jan 18, 2015 5:40 am

With help from Hiep Le Quy in figuring out where the hell is PDF build xml actually referring to, the Docbook PDF version finally rendered and uploaded to http://sourceforge.net/projects/red1/fi ... mpierePDF/

The code, now an OSGi plugin, has extensive tweaking to generate a new set of XMLs that are usable for FO PDF conversion as well as compatible for HTML rendering, renamed as http://red1.org/DocBook. It is integrated to a fresh set of Javadoc. And soon later i will figure out a rendering of the AD client (GardenWorld) data too for comprehensive meaning to the giant book.
Screen Shot 2015-01-18 at 5.31.28 AM.png
Screen Shot 2015-01-18 at 5.31.28 AM.png (87.31 KiB) Viewed 14911 times

HTMLDocBook.png
HTMLDocBook.png (240.68 KiB) Viewed 14905 times
red1
Site Admin
 
Posts: 2760
Joined: Tue Jul 06, 2004 3:01 pm
Location: Kuala Lumpur, Malaysia

Re: DocBook Documentation Project

Postby red1 » Wed Jan 21, 2015 7:55 pm

Have you ever wondered what is the underlying table data without the hassle of launching the ERP server or go into the database? Now it is all linked at the Window Tab level with raw data selected up to 100 rows maximum to allow for instant checking. The raw data gives insight to what the PKs and FKs are as a good boost and complement to any conventional debugging work. This is a developer's gift to another. Enjoy.

DatabaseLink.png
DatabaseLink.png (199.61 KiB) Viewed 14860 times


DocBookData.png
DocBookData.png (68.95 KiB) Viewed 14860 times
red1
Site Admin
 
Posts: 2760
Joined: Tue Jul 06, 2004 3:01 pm
Location: Kuala Lumpur, Malaysia

Re: DocBook Documentation Project

Postby red1 » Fri Jan 23, 2015 11:42 am

Tried the ePub format, though successful it is not useful as the content is too large and settings are not easy to study at the moment. Instead i went further ahead yesterday to explore the WebHelp version and it is most impressive. Now it is still generating, probably another 4 hours, and been uploaded in chunks. http://red1.org/idempiere/pr01.html

Screen Shot 2015-01-23 at 10.31.57 AM.png
Screen Shot 2015-01-23 at 10.31.57 AM.png (197.92 KiB) Viewed 14820 times
red1
Site Admin
 
Posts: 2760
Joined: Tue Jul 06, 2004 3:01 pm
Location: Kuala Lumpur, Malaysia

Re: DocBook Documentation Project

Postby red1 » Sat Jan 24, 2015 2:18 am

Finally it finished rendering which at the end the WebHelp build ant process created the index for fast searching. You can try it here http://red1.org/idempiere/index.html. It is based on mostly js files. The files can be ported to any local web server for self-access. It is quite complicated to learn DocBook to do it yourself so I can offer sending it at a small fee (please write to me red1()red1.org for it) or i can help render any end-user system's WebHelp (it takes 2 full days, so its a higher fee) and send the zipped files for putting in any web-server. Then you can examine your own AD with your own changes and a snap shot of your own data for fast debugging and troubleshooting even when your iDempiere system is down.
Been open source the generating code and the build xmls are all published at my http://bitbucket.org/red1/. Enjoy!

Screen Shot 2015-01-24 at 1.48.21 AM.png
Screen Shot 2015-01-24 at 1.48.21 AM.png (172.38 KiB) Viewed 14791 times
red1
Site Admin
 
Posts: 2760
Joined: Tue Jul 06, 2004 3:01 pm
Location: Kuala Lumpur, Malaysia

Re: DocBook Documentation Project

Postby red1 » Mon Jan 26, 2015 7:59 am

I made an improvement to the chapter and section nesting so that the main categories are summarised for better left panel viewing and browsing. The tab is now grouped properly for the table info to appear same page. Consider this a huge stub for content input. During Compiere days the Help/Comment fields are well described. Newer ones are not. Thus contributions are welcome. You can fetch the whole WebHelpHTML site zip here, run it from any PC or server, put in such content from time to time and send it back to me. Or you can just send me the suggested content for me to update back (give link where in http://red1.org/idempiere you are suggesting the content).

Summarie.png
Summarie.png (162.14 KiB) Viewed 14768 times
red1
Site Admin
 
Posts: 2760
Joined: Tue Jul 06, 2004 3:01 pm
Location: Kuala Lumpur, Malaysia

Re: DocBook Documentation Project

Postby red1 » Tue Jan 27, 2015 11:25 am

There is some weak namespaces usage and I got that corrected for online and PDF. Also added database snap shots for InfoWindows.
Screen Shot 2015-01-27 at 10.59.40 AM.png
Screen Shot 2015-01-27 at 10.59.40 AM.png (81.04 KiB) Viewed 14727 times

Screen Shot 2015-01-27 at 10.59.30 AM.png
Screen Shot 2015-01-27 at 10.59.30 AM.png (73.6 KiB) Viewed 14727 times

The final WebHelp and SimpleHTML files are uploaded in complete zips for own standalone use at http://sourceforge.net/projects/red1/files/p2/DocBook/
red1
Site Admin
 
Posts: 2760
Joined: Tue Jul 06, 2004 3:01 pm
Location: Kuala Lumpur, Malaysia


Return to iDempiere

Who is online

Users browsing this forum: No registered users and 2 guests

cron