Creating the Documentation Portal for your InterSystems IRIS Application

The ObjectScript language of InterSystems IRIS has a very powerful metadata engine called XData. This feature allows the creation of metadata definitions for your classes, to be used by the compiler or by programs that will extend the standard features of the language, based on the XData definitions of its scope.

An example is IRIS Publisher, an Open Source application from the community capable of collecting all XData definitions in HTML and / or Markdown format and generating a Web Portal with all the application documentation assembled from these XData elements.

See the whole process here:

Let's see a practical example, follow the steps:

1. Access the link https://openexchange.intersystems.com/package/IRIS-Publisher to download IRIS Publisher.
2. Clone the project repository in git in a local folder of your choice: git clone https://github.com/yurimarx/iris-publisher
3. Open the project's source code. It is in the iris-publisher folder. We will create some XData elements.
4. Go to the Person class inside src / dc / Sample. Inspect the two example XData definitions between lines 34 to 43.
   /// Documentation for Person in HTML

   XData PersonDocHtml [ MimeType = text/html ]

   {

   <h1>This is the Person class</h1>

   }

    

   /// Documentation for Person in Markdown

   XData PersonDocMarkdown [ MimeType = text/markdown ]

   {

   <h1>This is the Person class in MD</h1>

   }
5. There are 3 large blocks, the text after ///, where it is possible to write a description of the XData element; the very definition of XData and MimeType (only HTML and Markdown are captured) and finally, between {}, all the HTML or Markdown content that will compose your documentation. In this example we use both, but we recommend defining only 1 of them.
6. It is possible to annotate all classes of the project, or part of them with XData, creating a very complete documentation of your application.
7. After documenting your classes using XData, we will compile the project documentation, in the terminal, execute: docker-compose up -d --build
8. After execution, your instance will be live and you will be able to run the IRIS Publisher API.
9. Run http://localhost:52773/swagger-ui/index.html?Url=http://localhost:52773/api/mgmnt/v1/USER/spec/crud#/default/UpdateDocConfig to define title, developer information and describe your application, use the following content as an example:

   {
   "SiteName":"Publisher",
   "Summary":"Documentation of the Publisher",
   "Description":"This an Application to generate documentation from XDATA",
   "DeveloperName":"Yuri Gomes",
   "DeveloperEmail": "yurimarx@gmail.com",
   "DeveloperWebsite": "ymservices.tech"
   }

10. Run http://localhost:52773/swagger-ui/index.html?url=http://localhost:52773/api/mgmnt/v1/USER/spec/crud#/default/InitiatePublisher to generate the documentation and start Documentation portal for your application.
11. Go to http: // localhost: 8000 and see all the documentation online!
12. If you enjoyed, vote in my app: https://openexchange.intersystems.com/contest/current