ProvideX Class Documentation - Generate Documentation

This contributed tool requires that a resource in the source folder of a ProvideX project be selected in the 'Navigator View'. This resource can be the source folder or any resource in that folder (or a sub-folder).

The PvxDocs tool is selected from the list of available tools and the "Run" button is pressed to begin processing the selected folder (and sub-folders) or resource.

Setup

A setup panel will display to enable fine-tuning of the documentation to be generated.

PvxDocsRun - Setup

This panel allows adjustments to be made to the default information entered through the configuration panel:

Document Format

Output File Type: The type of file(s) to be generated (HTML, CHM, or Mediawiki-compatible XML export file)
Link to Pages: Method to use when creating links to other documentation files (Direct, Javascript: Same Page, Javascript: Separate frames)
Direct Links - Strip Text: Should text be stripped from path when using Direct Links to other documents
Value to Strip: Value to strip from the beginning of folder/file path in document links

Generation Information

Output Directory

The directory where the generated files will be created.

Wiki Parent Page

This option is available only when generating the Mediawiki XML export file and is used to set the import location for the generated content.

CHM Documentation Topic

This option will be used as the primary topic for the generated CHM file.

Javadoc Root Directory

Relative path (to output folder) for Javadocs referenced in generated documentation.

Set the project-specific property pvxdoc.Javadoc_Root to set the default value of 'Javadoc Root Directory' used when generating PvxDocs for the project.

Document Generation

Create Folder Structure: The folder structure of the project will be created in the output directory.
Use Folder Structure for Menu: This option is available only for HTML output when generating separate files for each class.
Skip Classes not documented: Do not generate class documentation for any class where no documentation has been added to the source file.
Include 'LOCAL': Include LOCAL property and function definitions documentation in the generated content.
Include Property assignment: Include the assignment information for any property assigned a value as part of the definition
Set Modification Date: Set the modification date/time of the generated documentation file(s) to match the modification date/time of the source file

Start Generate

A new view will be displayed to track the progress of the documentation generation process. While the source files are processed, click the 'Cancel' button to abort the document generation process.

PvxDocsRun - Process Log

Verify Generated Document(s)

Once the process has been completed, click the 'View Docs' button to view the generated documentation, or click the 'Close' button to close the view.

PvxDocsRun - Process Log

Viewing Content

After closing the log window, Viewing the generated documentation will depend on the output format that was chosen on the setup panel for the document generation process:

HTML

In a browser, simply open index.html to view the navigation menu and select the class documentation to display.

CORS (Cross Origin Resource Sharing) will block loading of page content when using a modern browser and attempting to view documents generated using the 'Same Page' option for linking to documents unless the files are hosted on a web server.

Microsoft HTML Help files (CHM)

On a MS-Windows machine, simply open the pvxdoc.chm file; a CHM viewer is required to open the file on machines using other operating systems.

After the CHM file is saved on a MS-Windows system, the security settings for the file must be adjusted to enable the content to display. In MS-Windows Explorer:

locate the file,
right click on the file and choose properties from the pop-up menu
at the bottom of the "General" page, click the <Unblock> button and then click <OK>

Mediawiki-compatible XML Export File

The documentation generation process will create at least two files named in the format 'PvxDoc_WikiExport_###.xml' and place them in the output folder.

The highest numbered file contains the parent page and sidebar navigation content and should only be imported when updating ALL content for a topic.

First, log in to the wiki as a user who is authorized to create (or modify) content and import pages.

Import NEW Content / Update existing content

The export files must be imported into the wiki site before it can be viewed.

Go to the 'Special:Import' page on the wiki site; this page can be accessed from "Special Pages" under the "Toolbox" menu.
For each of the export files:
- Select the export file
- Enter a comment to describe the content to be imported. This comment will be written to the change history for the wiki site.
- Click the <Upload File> button to begin the import process.
The time to complete the upload will depend on the size of each file.

If the generated documentation is for a subset of the classes and is intended to update existing content, or add missing (or new) content, the highest numbered file should NOT be imported - it will replace the content of the parent page and sidebar with the partial content.

Manual Update of Parent Page / Sidebar

When the generated documentation is for a subset of the classes, the parent page and navigation sidebar must be updated manually to merge the new content with the existing content.

Open the highest numbered export file in a simple text editor
Locate the first page tag - this will be the beginning of the parent page.
The next line will contain the name of the parent page between two title tags. The content of the page will be between two text tags.
Go to the page on the wiki site with this name and select to edit the page.
- In the Wiki editor, determine the location where the new content should be placed or the content to update.
- Copy the content from the text editor and insert/replace in the Wiki editor.
- Repeat until all of the new content for the page has been merged.
- A closing page tag will indicate where the information for the page ends.
Locate the next page tag - this will be the start of the content for the navigation sidebar.
The next line will contain the name of the parent page between two title tags. The content of the page will be between two text tags.
Go to the page on the wiki site with this name and select to edit the page.
Repeat the steps above to merge the new content into the existing navigation sidebar content.

After all of the files are imported (updated), go to the parent page to view the new content.