HTML Format with ISE's Stylesheet |

With gedoc, it is possible to generate HTML documentation out of an Eiffel project, using the same stylesheet used by the HTML documentation generated by ISE EiffelStudio. See Producing and Exporting Documentation for more details about the documentation format `html-stylesheet` from ISE EiffelStudio.

## Generating Documentation for an Eiffel Project

In order to generate HTML documentation which is very similar to the one produced by the following command-line (with ISE toolbox):

> `ec -filter html-stylesheet -all -config project.ecf`

you should use the following command-line:

> `gedoc --format=html_ise_stylesheet --library-prefix --output=some_output_directory project.ecf`

where `project.ecf` is the ECF file describing the Eiffel project, and `some_output_directory` is the directory where the HTML files will be generated. Note that an Xace file can also be used in place of the ECF file. The command-line option `--library-prefix` tells gedoc that HTML class files should be generated in a subfolder of the output directory whose name is the name of the Eiffel library containing these Eiffel classes (one subfolder per library). The command-line option `--force` can be used when you run this command several times to update the documentation after some modifications in the Eiffel class. It will tell gedoc to overwrite the files which already exist. Without this option, files will not be overwritten and gedoc will emit an error message. Alternatively, the command-line option `--interactive` can be used. It will ask confirmation to the user before overwriting files. Finally, if you want to generate HTML documentation only for a subset of the classes in your Eiffel project, you can use the command-line option `--class` with some wildcards.

## Generated Files

For each Eiffel class `FOO`, gedoc generates three HTML file: `foo.html`, `foo_chart.html` and `foo_links.html`. The file `foo.html` contains a pretty-printed, colorized and hyper-linked version of the class text. The file `foo_chart.html` contains general information about the class, the list of its parent classes, and the list of exported features (both declared in the class text and inherited from ancestors). Note that in order to comply with the original `html-sytlesheet` format from ISE EiffelStudio, features declared in class `ANY` are not listed here, unless redefined in a descendant. And finally the file `foo_links.html` lists the parent classes of the class, its heirs (other classes having this class as parent), its direct client classes and supplier classes.

Each HTML file has a natigation bar at the top and bottom of the page. The button `Classes` lists all classes in the Eiffel project, with the "description" text of their "note" clause (formerly known as "indexing" clause). The button `Groups` lists all Eiffel libraries used in the project, and the button `Group hierarchy` also lists their clusters. Clicking on the name of an Eiffel library will then display the list of classes in this library. The button `Chart` shows the file `foo_chart.html` (already mentioned above) for the class `FOO` currently displayed. The button `Relations` shows the file `foo_links.html`. The button `Text` shows the file `foo.html`. Finally, in the text field `Go to:` you can type the name of a class, then type "Enter" to jump to that class.

## Why yet another HTML Documentation Generator?

At work, as part of our DevOps effort, we have a Continuous Integration cycle and Continuous Delivery cycle which have to process 20,000 classes. During these phases, we generate HTML documentation out of these Eiffel classes. Here is the performance that we get when using ISE original `html-stylesheet` format:

    	ecb.exe -config integration.ecf -filter html-stylesheet -all
    		44 minutes
    		RAM: 3.9 GB
    		EIFGEN: 3.0 GB

This is way too slow within a Continuous Integration cycle and Continuous Delivery cycle. Knowing that gelint is super fast to analyze huge Eiffel systems (here, more than 20,000 classes), we tried to use the same code as gelint as a front-end of gedoc to generate similar HTML files. The results were up to our expectations:

    	gedoc.exe --format=html_ise_stylesheet --force --library-prefix --output=some_output_directory integration.ecf
    		2 minutes 48 seconds
    		RAM: 3.0 GB
    		No disk usage

This is when gedoc has been compiled with the Gobo Eiffel Compiler (aka gec) with no garbage collection. Here is what we get when gedoc is compiled with gec using the Boehm GC:

    	gedoc.exe --format=html_ise_stylesheet --force --library-prefix --output=some_output_directory integration.ecf
    		2 minutes 56 seconds
    		RAM: 2.7 GB
    		No disk usage

Starting with Gobo Eiffel 4.2, gedoc can now take advantage of multi-threading. Following are the results on a 4-CPU machine with no garbage collection:

    	gedoc.exe --format=html_ise_stylesheet --thread=4 --force --library-prefix --output=some_output_directory integration.ecf
    		1 minute 1 second
    		RAM: 3.0 GB
    		No disk usage

and when using the Boehm GC :

    	gedoc.exe --format=html_ise_stylesheet --thread=4 --force --library-prefix --output=some_output_directory integration.ecf
    		1 minute 4 seconds
    		RAM: 2.7 GB
    		No disk usage

This is still acceptable as part of a Continuous Integration cycle and Continuous Delivery cycle.