Adventures on the edge

Learning new development technologies
    "When living on the bleeding edge - you sometimes have to bleed" -BillKrat

Using ApexDoc with Welkin Suite

The Welkin Suite Spire R4 (Version 1.1.3.4) Salesforce development platform has a very impressive set of features.  I particularly love the ability to step through my code using the debugger while viewing variables, seeing my code coverage for my unit test (in color), and the ease in which I can deploy from my sandbox to my developer environment (DE) without ever going to a command prompt – everything is point and click, high performance, and easy to use.

I did have a major set back on this last release.  When I right clicked on my class name I saw a feature called Generate Apex Doc For Current Context.  I wasn’t sure what this was, but after a little research found the source code on GitHub along with documentation – I was now going to have to redo all of my documentation…  The set back was not from having to support the ApexDoc format (the Welkin Suite made this easy), but the work I was going to have to do so that the apexdoc.jar application would work seamlessly from within the Welkin Suite.   This required me to add features to ApexDoc, released as GwnV1.x.

image

My source code fork of the ApexDoc application allowed me to do just this [while maintaining backwards compatibility] I added default features that only require the apexdoc.jar file to be dropped into the solution folder and three entries made to the External Tools menu – steps shown below.

To setup the Welkin Suite to use ApexDoc (GwnV1.x) do the following:

Add the apexdoc.jar application to the Welkin Suite Tools menu:

  1. Click on Tools
  2. Click on External Tools…
  3. Fill in the External Tools dialog as shown on the right

With the above settings in place you can select “DOCS: Execute ApexDoc” from the Tools menu which will execute apexdoc.jar using the default settings.

Note: the apexdoc.jar file needs to be place in the solution direction for the defaults to work correctly.

DocApex

001

Note: above I indicated that the apexdoc.jar file needs to be in the solution folder, to be clear it is assumed that you saved your .sfln file in the same folder as your project file (so that the src folder is at the root as shown below).   If you have multiple projects, each with their own documentation, then you will want to ensure an apexdoc.jar file is dropped into each project folder (or you can put apexdoc.jar in your path and configure the switches).

ApexDocLocation


Once the apexdoc.jar application is executed it will generate the applicable help files and place them in a folder called ApexDocumentation in the solution folder.

If your solution folder has a folder called ApexDocContent with the following files they will be automatically used:

  1. .header.html
  2. .home.html

The .header.html file contains the logo and heading information for your application help docs.  In the example below the logo for Global Webnet, LLC is shown.  The .home.html file will display on the “Home” (default) tab of the help page.

DocView

002


The final configuration made in external tools is for the “Edit” feature; this will permit you to easily edit the HTML content for your help pages.   In my case I am using Visual Studio Code, it is a free editor that easily handles html, css, and javascript.

I added ./ApexDocContent to the arguments of the code.exe application with a initial directory of the solution folder.   When it executes it loads the application ready to start editing the html documents used by the help system.
DocEdit

Note above [in the screen shot of the documentation] that I have a blue box around a @group Configuration tag and I configure the @group-content location to the ApexDocContent folder.   Below I created a configuration.html it will be looking for.

003

 

Below I show what the .home.html file looks like after editing it in the above window:

004

The solution folder for my CPT application has the apexdoc.jar java application and the ApexDocContent folder which the ApexDoc (GwnV1.x) has been revised to support.  These are the only additional requirements you will have to comply with to take advantage of the ApexDoc features

Click HERE to get the contents of the ApexDocContent folder as well as the latest apexdoc.jar file.

SolutionFolder

When the apexdoc.jar application is executed it will copy all files (that are not html documents) to the ApexDocumentation folder so that they are available for your documentation.   The html files are not copied because the ApexDoc application has already retrieved the information from them (between the body tags) and has inserted the content into documentation files in the ApexDocumentation folder using the same html filename – thus we need to ensure we don’t copy the html files over (the ApexDoc GwnV1.x application takes care of this for you).

The highlighted files below show the minimum files I recommend for your AppDocContent folder.  The css, js, and logo files can be updated and your updates will replace the ApexDocumentation files so that if you make updates you can utilize them in your documentation, e.g. for THIS PAGE I added magnifier .css and .js files. 

ApexDocContent

Comments are closed