Tips_todo   >   Utilities   >   Utilities (All Contents)

Code Documenter

Code Documenter is the utiity 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 Omnis Studio application.

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, tipsCodeDoc.lbs. Set the $defaultname property of the library to tipsCodeDoc, 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 to move the documention at any time.
  2. Copy the oCodeDocProperties_template object from the tipsDocs library to your library.
  3. Rename the copied object to oCodeDocProperties.
  4. Modify the object's method return values as follows:
    • $:GroupName - Set the return value to an appropriate group name. Your group will show up in the Group Selector droplist of the StudioTips Browser toolbar.
    • $:FTPUserName - This is set to temp@studiotips.net. You can leave it for testing purposes, and later inherit the superclass method which will allow you to enter the value and saves it locally.

      You can the change the other return values later on for you own code documentation.
  5. 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.
  6. 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.
  7. 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.
  8. Add another method @10 Topic 1 and enter some text in the method description.
  9. Add another method @20 Topic 2 and enter some text in the method description.
  10. 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 tab pane will display your About object and 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.

    Warning

    If you press F1 or F9 while in the text entry field your last text editing will be lost because F1 and F9, do not generate an evAfter event and your changes are lost when the StudioTips Browser window returns to the front. To avoid this click the Sample Code list before pressing F1 or F9.

  3. Close and reopen the StudioTips Browser window. Your new text should be displayed in the documentation field.
  4. Double-click a line in Sample Code section. This opens your object class in the IDE.
  5. Add a method to the object class. Name it @15 Topic 1.5. Close the IDE.
  6. Close and reopen the parent node in the StudioTips Browser treelist. The new method should be listed as a child node 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

Code Documenter 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 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 on in the temp folder you created on the desktop. The file will then be uploaded to the temp 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.

Sync Styles

If you copy a #STYLE class from one library to another library (target) the $fieldstyle properties in the window classes and report classes of the target library can get severely messed up.

SyncStyles solves this problem by using notation to modify/add styles in the target library to match the master library.

SyncStyles does not delete styles from the target library.

To open the SyncStyles utility click the Open Sync Styles button in the StudioTips Browser.

syncstyles.gif

StudioTips Documentation - Copyright 2006 Vencor Software