How to generate Doxygen documentation (OBSOLETE PAGE)


WHAT TO DO

  • Login as lcgspi@lxbuild003
  •  cd ~lcgspi/scripts/doxygen
  • There is one file _tag.sh per project. Forget the files with numbers in the file name.
  • Edit the file PROJ_tag.sh (ex: pool_tag.sh) and change the value of PROJTAG to the new tag. Run the PROJ_tag.sh script.

Example:

 more pool_tag.sh
#! /bin/sh

PROJTAG=POOL_2_0_6
...

  • Update the "index.html" file in output directory to include the new link to the generated release, in the right order:

emacs /afs/cern.ch/sw/lcg/app/spi/doc/doxygen/output/index.html

BASIC IDEA

The doxygen automatic generation system created in SPI/Code Documentation component is basically a set of scripts and a directory structure created to maintain the nightly generated Doxygen documentation in a web published frame.

The idea is, given a release that must be generated, catch its /src directory in its release area as origin for the source code. Then configure the appropriate files and web pages, thus preparing the generation to be ran. At the end, we get a set of web pages (and possibly a pdf) hanging from the root of the project, with the desired documentation.

With the scripts, generation and addition or removal of new releases are supported, and the directory structure is thought to have a simple way of storing not only all the generated documentation, but also the web templates, the scripts theirselves, or the Doxygen configuration files.

We review in the following section this directory structure, and we talk about what scripts and when they're called in the third one. In the last section, a number of little tasks that the maintainer should do is listed.

Note: The Doxygen maintainer should be familiarized with the LXR system before understand the SPI structures, that are more complicated than the normal use.

DIRECTORY STRUCTURE

The directory structure for doxygen is rooted at:

/afs/cern.ch/sw/lcg/app/spi/tools/latest/data/doxygen

and consists in the directories that follow:

  1. /config --> It contains one directory per project, and inside a file called "taglist.conf" where all the documented releases from the project are listed. This is used by the regenerator of documentation to know what releases to generate.

2) /logs --> It contains one directory per project, and inside one directory per release. Here the logs of the

execution for that release are stored. Each file is named with the date of generation and the extension

.log

3) /output --> This is the "root" for the web pages structure. The file "index.html" is stored here, and every project

has its own directory, with a symbolic link per release, pointing to the real storage place of the doxygen

output.

4) /references --> Here, all the reference tag files are stored. These are used to reference one release from another.

5) /releases --> This directory is where the generated documentation is stored, and it is structured by project and

release. This is pointed by the links below the /output directory explained in point 3.

The ideal is to keep this under AFS area, but, until all projects have included this in their

release process. Even at that moment, it will be useful to store old releases, that cannot be

included in the AFS area.

6) /support --> This is where standard Doxyfiles, logos and web templates are stored.

SCRIPTS

The scripts are stored at:

/afs/cern.ch/sw/lcg/app/spi/tools/latest/scripts

and are the following ones:

1) lcg-doxygen-generate.sh --> Generate a release. This script has a lot of options that should

be examined with the -h option.

1) lcg-doxygen-pdf.sh --> The same as "lcg-doxygen-generate.sh" but it creates a PDF document

instead of web pages.

2) lcg-doxygen-create-project.sh --> Include a project in the /config directory as explained before

3) lcg-doxygen-create-tag.sh --> Include a release in the "taglist.conf" file as explained before

4) lcg-doxygen-check.sh --> Check if there are new releases in the AFS area without generated documentation.

This is the automatized way to inform the maintainer about when to include

new stuff.

WHAT THE MAINTAINER SHOULD DO

Usually, the basic tasks of the maintainer of SPI Doxygen Support are the following ones:

- Receive the nightly e-mails to check that all the automatized tasks are going well.

Automatized tasks are:

    • Nightly snapshot generations.

    • Whole generation each month (at 15th day).

    • Nightly check for new releases.

- Include new projects: With the "lcg-doxygen-create-project.sh" script

- Include new releases: With the "lcg-doxygen-create.tag.sh" and the "lcg-doxygen-generate.sh" scripts.

Don't forget to update the "index.html" file in /output to include the new link to the generated

release in its appropriate place.

emacs /afs/cern.ch/sw/lcg/app/spi/doc/doxygen/output/index.html


/afs/cern.ch/sw/lcg/app/spi/doc/doxygen/output/ 


Seal Snapshot is here:

/afs/cern.ch/sw/lcg/app/spi/doc/doxygen/output/SEAL/snapshot/doxygen

generated with the script inthe cchek out area.

>>> Prelimnary information

To generate the snapshot run the script seal_snap.sh in /home1/aimar@apiwgs01

-- Main.aimar - 26 Jan 2005

Edit | Attach | Watch | Print version | History: r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r1 - 2005-12-01 - AlbertoAimar
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    SPI All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback