Question
YURI MARX GOMES · Nov 24, 2020

Generate HTML source code documentation

Hi community!

Is it possible generate HTML documentation to my project ObjectScript classes (.cls)?

In Java we use Javadoc to do it. Javadoc get class comments and java metadata information and when I execute javadoc -d doc src\*, I get whole html documentation to my classes. Has IRIS something like javadoc? Is it documatic? If yes, how can I use it?

10
2 2 12 208
Log in or sign up to continue

Hi @YURI MARX GOMES ,

I don't know.

If nothing exists:

Perhaps we can write a script to call CSP.Documatic.PrintClass.cls and dump the html response into file.

ex : /csp/documatic/%25CSP.Documatic.PrintClass.cls?PAGE=CLASS&LIBRARY=%25SYS&CLASSNAME=%25Library.Integer

A %Net.HttpRequest is not required.   I guess we can create a %request object,  redirect the IO and calling OnPage method.

Great. But these solutions depends IRIS server online, because links are related to the documatic server. In javadoc the documentation can be read offline

Your local instance has its own local version of documatic. So, it's available offline.

It's useless on your local dev, but depending your goal :
You can try to dump

zzDumpDoc(pkg, targetDir="c:\dev\testdumpdoc\")
    new (pkg, targetDir)

    Do:'##class(%File).DirectoryExists(targetDir) ##class(%File).CreateDirectoryChain(targetDir)

    Set pkgDot = pkg _ ".", class = pkgDot, restore = 0

    If $Isobject($Get(%request)) {
        Set oldRequest = %request
        Set oldResponse = %response
        Set oldSession = %session
        Set restore = 1

    }

    Set %request = ##class(%CSP.Request).%New()
    Set %response = ##class(%CSP.Response).%New()
    Set %session = ##class(%CSP.Session).%New("0123456789")
    Do %session.Unlock()

    Set %request.Data("PAGE",1) = "CLASS"

    For  {
        Set class = $Order(^oddDEF(class))
        Quit:$e(class,1,$l(pkgDot))'=pkgDot
        Set %request.Data("LIBRARY",1) = $namespace
        Set %request.Data("CLASSNAME",1) = class

        Set initialIO = $IO
        Set file = targetDir_class_".html"
        OPEN file:("NRW"):2
        USE file
        Do ##class(%CSP.Documatic.PrintClass).OnPage()
        USE initialIO
        CLOSE file
    }

    If restore {
        Set %request = oldRequest
        Set %response = oldResponse
        Set %session = oldSession
    }
    quit

There exits more elegant way to redirect the output (check the community).

Hi @YURI MARX GOMES!
I did a quick and dirty try during lunch in terminal:   

set %library=$namespace
set set %request=##class(%CSP.Request).%New()
set cdef=##class(%ClassDefinition).%OpenId("zrcc.EX.ISOS")     ; my classname
set file="my.html" o file:("WNS"):0 write $t     ;  1 if OK
use file d ##class(%CSP.Documatic).RenderClassPage(cdef,1)
close file

The result still holds references to /csp/...images  and data types  
     <image id=Im1 src=/csp/sys/images/ExpandedMarker.jpg height=. . . 
    <a href="%25CSP.Documatic.cls?PAGE=CLASS&LIBRARY=USER&CLASSNAME=%25String">%String</a>
that you might want to resolve as they are quite generic or you just ignore it .
My browser is very friendly  :-)

And that's the result:


Some polishing might be required
 

the generated file:
------------------------------------------------------------------------------------------
<br><p>
<nobr>Klasse <b>zrcc.EX.ISOS</b>
</nobr><p>Execute InterSystems ObjectScript over ODBC</p><a name="Anchor_Inventory"></a>
<table class="Label" cellpadding="0" cellspacing="0" cols="1">
<tr valign="center">
<td align="left" width="100%" >
<a href="#" onclick="expandIt(1); return false;" class="PackageChoice" title="Expand/Collapse Inventory" onmouseover="this.style.color = 'red';" onmouseout="this.style.color = 'black';">
    <image id=Im1 src=/csp/sys/images/ExpandedMarker.jpg height=15 width=16 border=0 align=bottom>
<nobr><b>Inventory</b></nobr></a>
</td>
</tr>
</table>
<br>
<div id="Id1" class="DivShow" style="">
<table class="Summary" cellpadding="0" cellspacing="0" cols="1">
<tr valign="center">
<th align="center">
Parameters
</th>
<th align="center">
Properties
</th>
<th align="center">
<a href="#Anchor_Methods">Methods</a>
</th>
<th align="center">
Queries
</th>
<th align="center">
Indices
</th>
<th align="center">
ForeignKeys
</th>
<th align="center">
Triggers
</th>
</tr>
<tr>
<td align="center" class="private">
</td>
<td align="center" class="private">
</td>
<td align="center">
<a href="#Anchor_Methods">3</a>
</td>
<td align="center" class="private">
</td>
<td align="center" class="private">
</td>
<td align="center" class="private">
</td>
<td align="center" class="private">
</td>
</tr>
</table>
<br/>
<br/></div>
<a name="Anchor_Summary"></a>
<table class="Label" cellpadding="0" cellspacing="0" cols="1">
<tr valign="center">
<td align="left" width="100%" >
<a href="#" onclick="expandIt(2); return false;" class="PackageChoice" title="Expand/Collapse Summary" onmouseover="this.style.color = 'red';" onmouseout="this.style.color = 'black';">
    <image id=Im2 src=/csp/sys/images/ExpandedMarker.jpg height=15 width=16 border=0 align=bottom>
<nobr><b>Summary</b></nobr></a>
</td>
</tr>
</table>
<br>
<div id="Id2" class="DivShow" style="">
<table class="Summary" border="0" cellspacing="0" cellpadding="1">
        <tr><th colspan="3" title="Bold for local member; italics for inherited; shaded for private; blue for client methods; strikethrough for deprecated.">Methoden</th></tr>
<tr>
<td  nowrap><a class="" href="#METHOD_Gset" title="zrcc.EX.ISOS">Gset</a></td>
<td  nowrap><a class="" href="#METHOD_Ping" title="zrcc.EX.ISOS">Ping</a></td>
<td  nowrap><a class="" href="#METHOD_Xcmd" title="zrcc.EX.ISOS">Xcmd</a></td>
</tr>
</table><br/>
<br/></div>
<a name="Anchor_Methods"></a>
<table class="Label" cellpadding="0" cellspacing="0" cols="1">
<tr valign="center">
<td align="left" width="100%" >
<a href="#" onclick="expandIt(3); return false;" class="PackageChoice" title="Expand/Collapse Methods" onmouseover="this.style.color = 'red';" onmouseout="this.style.color = 'black';">
    <image id=Im3 src=/csp/sys/images/ExpandedMarker.jpg height=15 width=16 border=0 align=bottom>
<nobr><b>Methods</b></nobr></a>
</td>
</tr>
</table>
<br>
<div id="Id3" class="DivShow" style="">
<a name="Gset"></a>
<a name="METHOD_Gset"></a>
<span class="external"><nobr>&#149 classMethode <b>Gset(glob As <nobr><a href="%25CSP.Documatic.cls?PAGE=CLASS&LIBRARY=USER&CLASSNAME=%25String">%String</a></nobr>, subs As <nobr><a href="%25CSP.Documatic.cls?PAGE=CLASS&LIBRARY=USER&CLASSNAME=%25String">%String</a></nobr>, val As <nobr><a href="%25CSP.Documatic.cls?PAGE=CLASS&LIBRARY=USER&CLASSNAME=%25String">%String</a></nobr> = "", dd As <nobr><a href="%25CSP.Documatic.cls?PAGE=CLASS&LIBRARY=USER&CLASSNAME=%25Integer">%Integer</a></nobr> = 1)</b>
as <nobr><a href="%25CSP.Documatic.cls?PAGE=CLASS&LIBRARY=USER&CLASSNAME=%25String">%String</a></nobr></nobr>
[ SQLProc = Gset ]</span><blockquote>
set / kill global over ODBC
subs = subscript in ( )
dd = $data of source during global copy</blockquote>
<a name="Ping"></a>
<a name="METHOD_Ping"></a>
<span class="external"><nobr>&#149 classMethode <b>Ping()</b>
as <nobr><a href="%25CSP.Documatic.cls?PAGE=CLASS&LIBRARY=USER&CLASSNAME=%25String">%String</a></nobr></nobr>
[ SQLProc = Ping ]</span><blockquote>
check connectivity</blockquote>
<a name="Xcmd"></a>
<a name="METHOD_Xcmd"></a>
<span class="external"><nobr>&#149 classMethode <b>Xcmd(cmd As <nobr><a href="%25CSP.Documatic.cls?PAGE=CLASS&LIBRARY=USER&CLASSNAME=%25String">%String</a></nobr>, ret As <nobr><a href="%25CSP.Documatic.cls?PAGE=CLASS&LIBRARY=USER&CLASSNAME=%25String">%String</a></nobr> = "")</b>
as <nobr><a href="%25CSP.Documatic.cls?PAGE=CLASS&LIBRARY=USER&CLASSNAME=%25String">%String</a></nobr></nobr>
[ SQLProc = Xcmd ]</span><blockquote>
eXecute Command over ODBC
name of local variable for return value</blockquote>
-------------------------------------------------------------------------------------------
​​​

If I try navigate the docs with iris down, Is it works?

IRIS HTML documentation is a dynamic site, depends on documatic server and source code installed into an IRIS instance. Has it static website generation, with an option to navigate without classes compiled into an IRIS instance?

Today people wants see documentation without to have install servers, inside github or local browser. Is it possible if docs is html static, but documatic is a server app.

Official online documentation for IRIS, available only online or offline as PDF only.

Class Reference Documatic, working only when the server is up and running. 

No static HTML documentation at all.

I encounter this issue fairly often, but I need not a complete documentaiton but rather Interoperability production documentation.

As all the class info is also available as a %Dictionary package I just query it and generate XLSX.

Here are some queries to get started (but they usually need to be adjusted on per-project basis). Also queries should be rewritten to use SubclassOf proc instead of the current matching. Also I'm not sure why I don't pass filestream directly. That also  needs to be fixed.

 
Queries