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. 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.