Tips   >   Utilities   >   Code Documenter

Code Documenter

is the utiity built into StudioTips which is used to write, edit, and upload all of the documentation found in StudioTips.

Code Documenter has been written so that it can be used to write, edit, and upload documentation for any develoepr's Omnis Studio application.

This sections provides you with a tutorial where you will create your own documentation using Code Documenter and upload it to the studiotips.net site where you will view it with a web browser.

Getting Setup

The following tutorial will get you started with writing your own Code Documentation:

  1. Create a library where you will store your documentation. For this tutorial, name the library, myDocs.lbs. Set the $defaultname property of the library to myDocs, so that the library name won't be changed if someone changes the file name.

    Your documentation can be stored in the same library as the real code, or you can choose to store your documentation in a separate library. You can easily move the documention at any time.
  2. If the tipsDocs library is not visible in the F2 Browser, select Show Tips Libraries in the Tips menu.
  3. Copy the Startup_Task object from the tipsDocs library to your library. Overwrite the existing Startup_Task.
  4. Copy the oCodeDocProperties object from the tipsDocs library to your library.
  5. Modify the object's $:GroupName method to return My Documentation or another appropriate group name. The group name will show up in the Group Selector droplist of the StudioTips Browser toolbar.
  6. Modify the object's $:URLCodeDocsFolder method to return 'http://www.studiotips.net/temp/'.
  7. The other property methods can be modfied later on to suit your requirements.
  8. Create a folder in your library. Name the folder @ mydocs. Note the space between the @ character and the name.

    The folder class name, less the @ prefix, will map to a folder on the website. This is the root folder for this group's documentation.
  9. Inside the folder create an object class. Name it @10 About ;; GroupName. GroupName is the name you gave to your group in the oCodeDocProperties object.
  10. Go to the class methods of the object and add a method @00 About. Enter some text in the method description entry field located directly below the code list in the method editor.
  11. Add another method @10 Topic 1 and enter some text in the method description.
  12. Add another method @20 Topic 2 and enter some text in the method description.
  13. Close and reopen the StudioTips Browser window. Your group should now be listed in the StudioTips Browser toolbar group selector droplist. Select your group in the droplist. The treelist will list the topics.

Entering Documentation

  1. Right-click anywhere in the documentation field of the StudioTips Browser and select Switch to Edit Mode.

    switchtoeditmode.gif



    The editor toolbar will be added to the StudioTips Browser window's toolbar. You are now able to edit text in the documentation field.
  2. Enter some text in the documentation field.

    The text you enter is automatically saved to your object's method description when you leave the field.
  3. Close and reopen the StudioTips Browser window. Your new text should be displayed in the documentation field.
  4. Double-click a line in Method Code section near the bottom of the StudioTips Browser window. This opens the object class in the Method Editor to the current method.
  5. Add a method to the object class. Name it @15 Topic 1.5.
  6. Close the Method Editor window.
  7. Click the Rebuild Cached List buttonin the StudioTips Browser window toolbar (blue arrows icon to the left of the group selector droplist). The new method should now be listed as a treelist in the order you specified.

    Tip

    The @## prefix controls the sort order of objects and methods. Use the @50 prefix for all objects and methods you want sorted alphapetically.

Uploading Documentation

is written so that the documenation you create can be available locally and online. To upload the documentation you have created.

  1. Click the Code Documenter Preferences toolbar button beside the Groups Selector droplist. This opens the preferences window.
  2. Enter the FTP User Name: temp@studiotips.net
  3. Enter the FTP Password: pass
  4. Leave the FTP Initial Directory field empty.
  5. Click the open book icon next to the Local Code Docs Folder Path label. This prompts you to select a folder on your computer where the HTML files will be stored. Create a folder on your desktop and name it temp, then select. The path to the temp folder should be displayed in the field at the bottom of the Code Documenter Preferences window.
  6. Click the Connect button. This tests the FTP connection. All going well an FTP connection will be opened to studiotips.net and you will see a list of files and folders currently in the temp@studiotips.net root directory.
  7. Close the StudioTips - Code Documenter Preferences window to return to the StudioTips Browser window.
  8. Right-click one of the nodes in the treelist and select Create and Upload HTML Files For Selected Nodes.

    An HTML file will be created in the temp folder you created on the desktop. The file will then be uploaded to the temp directory on the studiotips.net website.
  9. Click on the Go to URL button at the bottom of the StudioTips Browser window. This will open up your default web browser to the HTML file which you just uploaded.

Creating TOC and All Contents Files

You can also create TOC (Table of Contents) and All Contents files for your documentation.

  1. Right-click on the treelist and select Create and Upload All HTML Files (including TOC and All Contents files)

    This will create and upload all the HTML files for the documentation in the library, plus create a tableof contents file (default index.html) and an all contents file (default all.html) for each folder in the code documentation tree in your library.
  2. Alt/Option click the Go to URL button at the bottom of the StudioTips Browser window.

    This will open the default web browser to the table of contents page.

Adding Images

Text only documention is okay, but they say a picture is worth a thousand words. Screenshots are an important part of any code documentation. To add screen shots to your documentation:

  1. Click anywhere in the documentation field.
  2. Click the Image icon in the StudioTips Browser tooblar. This inserts an image source tag in your documentation.
  3. Enter screenshot.gif in between the double quotes of the image source tag.

    You could enter a full http address in the image source. If you just enter a file name, Code Documenter, fills in the rest for you based on the Code Docs Folder Path / Images Folder Name as specified in the preferences. The rest of the path to the image file mirrors the path to the HTML file.
  4. Right-click on a node in the treelist and select Create Images Folders for Selected Nodes.

    This creates the sub-folders in the temp folder on your desktop.
  5. Take a screen shot of some window on your computer screen.
  6. Open the image in an image manipulation program (e.g. Adobe Photoshop) and adjust the image for the web.

    This could mean resizing the image and changing it to a GIF or JPG file so that it will load faster into a web browser.

    You should adjust the image to 72 or 96 dpi and a reduce or crop the image to maximum width of 580 pixels, so that it will load quickly and fit properly on a pages printed from a web browser.
  7. Save the modified screenshot image to the images folder inside the temp folder on your desktop. Name the saved image as screenshot.gif.

    I prefer to use all lowercase for website folder and file names. You can use mixed case names.
  8. Right-click on a node in the treelist and select Upload Images for Selected Nodes.

    This opens an FTP connection with the server and uploads the images in the local folder to the server automatically creating any sub-folders on the server.
  9. Right-click on a node in the treelist and select Create and Upload HTML Files for Selected Nodes so that your revised page with the image source tag is uploaded to the web server.
  10. Click the Go to URL button at the bottom of the StudioTips Browser window. Your documentation page should now load with the screenshot image. You may need to press the reload button in the web browser.

Adding Section Tabs

As your documentation grows you may want to divide it into logical sections which will be displayed in separate tabs in the StudioTips Browser window.

To create sections:

  1. Select the @ mydocs folder in the F2 Browser
  2. Click the New Folder button to create a subfolder inside @ mydocs.
  3. Name the folder @10 About.
  4. Drag the @10 About ;; My Documentation object class from the @ mydocs folder to the @10 About folder.
  5. Select the @ mydocs folder in the F2 Browser
  6. Click the New Folder button to create a subfolder inside @ mydocs.
  7. Name the folder @50 Tutorial.
  8. Double-click the @ @50 Tutorial folder in the F2 Browser
  9. Click the New Class button and create an object class inside the @ @50 Tutorial folder.
  10. Name the object class @10 Getting Started.
  11. Double-click the @10 Getting Startedobject class to get to its methods.
  12. Add an @00 About method to the @10 Getting Started object class.
  13. Add an @10 Step 1 method to the @10 Getting Started object class.
  14. Add an @20 Step 2 method to the @10 Getting Started object class.
  15. Close the method editor.
  16. Right-click the @10 Getting Started object class and select Duplicate.
  17. Rename the duplicate class to @20 Next Steps.
  18. Open the StudioTips Browser, select My Documentation in the groups selector, then click the Rebuild Cached Lists button. Two tabs, About & Tutorial, should now appear in the StudioTips Browser window.

Code Documenter Toolbar

The Code Documenter toolbar can be used to add special HTML tags to your documentation. Some of the tags are actual HTML tags, others are use to generate special tags used by CSS.

As you hover over each toolbar button a tooltip provides you with helpful information about the tag.

You can browse the StudioTips tips in the StudioTips Browser in Edit Mode to see how the tags are used.

Most of the tags which you see in Edit Mode are removed when you switch to View Mode.

Special @ Tags

There are some special @ tags which you can use in your documentation.

If you include and @SAMPLECODE:1 tag starting on a new line in your documentation, Code Documenter will replace it in View Mode and in the HTML generated with the actual code you put in that tip's method in the method editor.

The sample code in the method editor must begin with the @SAMPLECODE:1 tag and end with an @ENDSAMPLECODE tag.

Within the same tip you can have @SAMPLECODE:2, @SAMPLECODE:3,...

You can see how the following @SAMPLECODE tag works by switching back and forth between Edit Mode and View Mode in the StudioTips Browser.

; This is some sample code.
Calculate #S1 as 'Some value'

If you wish to include a demo with your documenation you simple need to enclose your demo code in tip's method with @DEMO and @ENDDEMO. When Code Documenter sees the @DEMO tag it automatically displays a Run Demo button in the StudioTips Browser window. You can specify the demo button text by appending it to the @DEMO tag. e.g. @DEMO: Open Demo Window

Summary

You now have the basics for creating documentation using Code Documenter. Feel free to use Code Documenter for generating your own documentation. The benefits of using Code Documenter are numerous:

  1. Documentation always right there imbedded with your Omnis Studio libraries.
  2. If you are using the VCS with multiple libraires, all of the developers can get the lastest documentation from the VCS, and can update the documentation directly through the VCS.
  3. Demos and actual Omnis Studio sample code can be included with the documentation.
  4. You don't have to switch to a different application to write and update the documentation. You simply open the StudioTips Browser, select the right group, and start writing!