[a1161c]: scripts / doxy / README  Maximize  Restore  History

Download this file

104 lines (74 with data), 3.6 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
Scripts to generate vxl documentation using doxygen

See how_it_works.txt for an overview.

Requirements:
The scripts assume that the following can be run at the command line:
- cvs
- doxygen   (see www.doxygen.org)
- texi2html (see http://techinfo.org or www.mathematik.uni-kl.de/~obachman/Texi2html)
             - If not available the book documentation won't be built,
			   but the main scripts should still run without breaking.


Quick setup on Debian/Ubuntu:

aptitude update
aptitude safe-upgrade
aptitude install cvs doxygen texi2html build-essential linux-headers-`uname -r` graphviz netpbm

You need "netpbm" for the pstopnm convertion script and "graphviz" to make nice inheritance diagrams.
Although doxygen will still work without these.

Usage:
Arrange that the perl scripts in this directory are executable.
(eg "chmod +x *.pl" under unix).

You can then simply run:

./build_all_doc.pl -v $VXLSRC -f

to generate all the documentation and index in $VXLSRC/Doxy/html
(This assumes vxl_scripts is checked out into $VXLSRC. If it isn't,
 use the -s flag to indicate where vxl_scripts/doxy is).

Common parameters
-----------------
All the scripts take one or more of the following parameters:
-v VXLSRC  : Defines where to find the code (eg VXLSRC/vxl/vnl)
-s script_dir : Defines location of script directory
                (default is $vxlsrc/vcl_scripts/doxy)
-o OUTPUTDIR : Defines base output directory (default is $vxlsrc/Doxy)
               (html will be put in $OUTPUTDIR/html)
-l ctrl_file : Defines file containing list of libraries and dependencies, books,
			and packages. (Default is $script_dir/data/library_list.txt)
-u : Update each package from CVS and only build if changes occur
-f : Force build of everything (useful every now and again to keep things in sync).


To generate documentation for your own modules
----------------------------------------------

a) Check them out into $VXLSRC

  eg in our $VXLSRC we have
    - vcl
	  - vxl
	  - mul
	  - isbe_apm  (local package)
	  - isbe_qtools (local package)

b) Create a library_list.txt file, based on the one in the data directory,
   indicating the extra libraries you use.
c) Create a book_list.txt file, based on the one in the data directory,
   indicating the extra texi books you have written
d) Invoke

build_all_doc.pl -v $VXLSRC -l my_library_list.txt -o OUTPUTDIR [-f] [-u]

That's all there is to it.


Updating documentation on a webserver
-------------------------------------
The script update_webserver.pl is provided to allow you to easily update
stuff on a web server.  Basically it invokes build_all_doc.pl, but only
after it has first invoked checkout_packages.pl to ensure any new packages
you might be interested in have been checked out first.

This makes it easy to add a new package to the system and have its documentation
appear on the webserver (over-night if you invoke the script each night).

When a package is added to the repository, to make documentation
appear for it you should modify the library_list.txt file
The checkout_packages.pl tool will be used to make sure the package gets checked
out onto the webserver, so that its documentation can then be generated.

Possible improvements to be made:
---------------------------------
- Tidy up texi2html parameters - perhaps pass them in to the tools.

Debugging:
----------

Output of scripts often gets sent to $VXLSRC/Doxy/output - look at what is there.




 Authors
 -------
 These scripts were written by Tim Cootes (University of Manchester)
 based on a set of scripts originally written by Dave Cooper, with
 contributions from Ian Scott and Peter Vanroose.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks