Extension:DoxyWiki

HELP WANTED: I'm looking for someone who wants to continue this extension. [mailto:rnrneverdies@gmail.com?subject=doxywiki%20future]

Please note: our download host sometimes is off line, try again later if it doesn't work!

More..: the english version of this page is in progress - see English. You can also use Google's machine translation.

Para que sirve Doxywiki
DoxyWiki es una extension para MediaWiki que integra la documentacion generada por la herramienta doxygen dentro de la funcionalidad de Mediawiki. En nuestra empresa, desde hacia tiempo utilizabamos exitosamente Mediawiki como herramienta central de documentacion y disenio de nuestros desarrollos, con la desventaja de tener otra interface para la documentacion de referencia de nuestro codigo fuente. Por tal motivo he desarrollado esta herramienta que espero les agrade y sea util.

Como funciona?
Esta implementado en 2 partes:

La primera parte es un desarrollo en c++ integrado a doxygen (vea: Instalacion y Configuracion) este genera la organizacion jerarquica de la documentacion construyendo archivos formateados y likeados entre si a la manera MediaWiki.

Luego se utiliza la segunda parte, desarrollada en PHP en la forma de una SpecialPage de Mediawiki. Esta es responsable de los Indices generales y la renderizacion final para mostrar al usuario.

Instalacion y Configuracion
Para utilizar la herramienta por ahora son varios pasos... suerte!

Descargar doxygen y compilar
Lo primero que debemos hacer es descargar la revision 629 del SVN de doxygen y compilarla a la manera indicada para asegurarons que esta ok.

para obtener los fuentes de doxygen ejecute:


 * 1) mkdir doxygen-svn; cd doxygen-svn
 * 2) svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk
 * 3) cd trunk
 * 4) ./configure
 * 5) make

Instalar el parche doxygen_r999_v9.patch
En la distribucion hay un archivo de extension .patch que es el parche que se debe aplicar a doxygen para que realize la salida con formato mediawiki.

.../doxygen-svn/trunk patching file wikidocvisitor.h patching file docvisitor.h patching file libdoxygen.pro.in patching file wikigen.cpp patching file doxygen.cpp patching file config.l patching file wikidocvisitor.cpp patching file pagedef.h patching file wikigen.h
 * 1) pwd
 * 1) cd src
 * 2) patch -p1 </location/of/doxygen_r999_v9.patch
 * 1) cd ..
 * 2) ./configure
 * 3) make

Instalar el componente PHP para MediaWiki
Dentro de la distribucion, hay una carpeta llamada Doxywiki. Esta debe ser copiada al directorio extensions de MediaWiki y como siempre se hace incluir en LocalSettings.php la siguiente linea...

require_once( "extensions/DoxyWiki/DoxyWiki.php" );

Ademas hay que subir a la wiki (con Upload File) las imagenes que estan en la carpeta DoxWiki/images/.

Procesar el Codigo Fuente Documentado
Lo siguiente es procesar el codigo fuente documentado con el archivo de salida de la compilacion del doxygen patcheado (.../doxygen-svn/trunk/bin/doxygen)

Para poder hacerlo necesitamos el archivo de configuracion de doxygen. Aqui hay un ejemplo: (llamado doxyconf.txt en este caso)

PROJECT_NAME          = My Project 1.0 PROJECT_NUMBER        = 1.0 OUTPUT_DIRECTORY      = /path/to/output/dir OUTPUT_LANGUAGE       = Spanish REPEAT_BRIEF          = NO ABBREVIATE_BRIEF       = ALWAYS_DETAILED_SEC   = NO STRIP_FROM_PATH        = /path/to SHORT_NAMES           = YES SEPARATE_MEMBER_PAGES = NO ALIASES                = BUILTIN_STL_SUPPORT   = NO DISTRIBUTE_GROUP_DOC   = NO SUBGROUPING            = YES EXTRACT_PRIVATE       = YES EXTRACT_STATIC        = YES SORT_BRIEF_DOCS       = YES SORT_BY_SCOPE_NAME    = YES SHOW_DIRECTORIES      = YES INPUT                 = MyProj.php MyProj.i18n.php docs/ FILE_PATTERNS         = *.php *.doc RECURSIVE             = YES EXAMPLE_PATH          = EXAMPLE_RECURSIVE     = NO IMAGE_PATH             = ALPHABETICAL_INDEX    = YES COLS_IN_ALPHA_INDEX   = 5 GENERATE_HTML         = YES HTML_OUTPUT           = html/ GENERATE_LATEX        = NO GENERATE_RTF           = NO GENERATE_MAN           = NO GENERATE_WIKI          = YES WIKI_PROJECT          = myproject WIKI_OUTPUT           = wiki/
 * :P

Luego ejecutamos:


 * 1) /path/to/doxygen doxyconf.txt

Esto generara la documentacion en fto doxywiki en la carpeta /path/to/output/dir/wiki/.

Ahora nos falta solamente configurar el proyecto ...

Configurar los proyectos de Doxywiki
Una vez instalado, y con la documentacion generada se debe crear un articulo con el nombre 'Mediawiki:Doxywikiprj'. Se recomienda protegerlo. En este se formatea por asi decirlo la tabla de proyectos doxywiki.

En esta tabla se asigna toda la informacion que esta extension necesita para generar acceder a los articulos y para la navegacion general, descripciones adicionales, etc. A partir de ella se crea el indice general.

Formato de Mediawiki:Doxywikiprj:

Continuando el Ejemplo:

myproject,My Project Title 1.0,/path/to/output/dir/wiki,/home/dev/src/,es,alpha,My Project Long Description. other,Other 4.2,/path/to/other/wiki,/home/other/src/,en,alpha,The other one.

Por cada linea en este articulo se hace considera un proyecto. Cada linea se divide en 7 columnas separadas por, (comma).

Significado de las columnas:


 * 1) nombre: el mismo nombre que se asigno en WIKI_PROJECT, tiene que ver con los indices.
 * 2) titulo: El nombre usado en el indice y la navegacion. Corto.
 * 3) pathwiki: el path donde se encuentran los archivos .wiki
 * 4) pathsrc: el path al codigo fuente (todavia no se usa)
 * 5) lang: el idioma en que esta escrita la documentacion. (todavia no se usa)
 * 6) estado: Estado de la documentacion (todavia no se usa)
 * 7) longdesc: Espacio para una descripcion detallada.

Una vez grabada esta pagina acceder a la pagina http://.../Special:DOXYWIKI y listo.

Enjoy!

English: DoxyWiki history and rationale
DoxyWiki is an extension for MediaWiki that integrates documentation generated by doxygen within the functionality of MediaWiki. In our company, for a long time we have successfully used Mediawiki in our development process, but we have used another documentation system for our source code. For this reason I developed this tool which I hope others will find pleasing and useful.

How it works
It is implemented in 2 parts:

The first part is a development in C++ integrated doxygen (see: Installation and Configuration) that generates the hierarchical organization of the building documentation and likeados formatted files to one another as MediaWiki.

Then use the second part, developed in PHP in the form of a Specialpage of Mediawiki. This is responsible for the overall and final renderings to show the user.

Installation and Configuration
To use the tool for now are several steps ... lucky!

Download and compile doxygen
The first thing to do is download the SVN revision 629 of doxygen and compile it as follows:


 * 1) mkdir doxygen-svn; cd doxygen-svn
 * 2) svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk
 * 3) cd trunk
 * 4) ./configure
 * 5) make

Install the patch doxygen_r999_v9.patch
In the distribution there is a file with filename ending in ".patch", which is the patch to be applied to make doxygen produce mediawiki-formatted output.

.../doxygen-svn/trunk patching file wikidocvisitor.h patching file docvisitor.h patching file libdoxygen.pro.in patching file wikigen.cpp patching file doxygen.cpp patching file config.l patching file wikidocvisitor.cpp patching file pagedef.h patching file wikigen.h
 * 1) pwd
 * 1) cd src
 * 2) patch -p1 </location/of/doxygen_r999_v9.patch
 * 1) cd ..
 * 2) ./configure
 * 3) make

Install PHP component for MediaWiki
Within the distribution, there is a folder called Doxywiki. This should be copied to your MediaWiki extensions directory and as is always done in LocalSettings.php include the following line ... require_once("extensions/DoxyWiki/DoxyWiki.php");

You have to climb to the wiki (with Upload File) images that are in the folder DoxWiki/images/.

Process documented source code
The following process the source code is documented with the output file compilation (.../doxygen-svn/trunk/bin/doxygen patched doxygen)

To do this we need the doxygen configuration file. Here is an example (called doxyconf.txt in this case) # :P PROJECT_NAME          = My Project 1.0 PROJECT_NUMBER        = 1.0 OUTPUT_DIRECTORY      = /path/to/output/dir OUTPUT_LANGUAGE       = English REPEAT_BRIEF          = NO ABBREVIATE_BRIEF       = ALWAYS_DETAILED_SEC   = NO STRIP_FROM_PATH        = /path/to SHORT_NAMES           = YES SEPARATE_MEMBER_PAGES = NO ALIASES                = BUILTIN_STL_SUPPORT   = NO DISTRIBUTE_GROUP_DOC   = NO SUBGROUPING            = YES EXTRACT_PRIVATE       = YES EXTRACT_STATIC        = YES SORT_BRIEF_DOCS       = YES SORT_BY_SCOPE_NAME    = YES SHOW_DIRECTORIES      = YES INPUT                 = MyProj.php MyProj.i18n.php docs/ FILE_PATTERNS         = *.php *.doc RECURSIVE             = YES EXAMPLE_PATH          = EXAMPLE_RECURSIVE     = NO IMAGE_PATH             = ALPHABETICAL_INDEX    = YES COLS_IN_ALPHA_INDEX   = 5 GENERATE_HTML         = YES HTML_OUTPUT           = html/ GENERATE_LATEX        = NO GENERATE_RTF           = NO GENERATE_MAN           = NO GENERATE_WIKI          = YES WIKI_PROJECT          = myproject WIKI_OUTPUT           = wiki/ Then run: This generates the documentation in fto doxywiki in the folder /path/to/output/dir/wiki/.
 * 1) /path/to/doxygen doxyconf.txt

Now we need only set up the project ...

Set Doxywiki projects
Once installed, and the documentation generated is create an item named 'Mediawiki: Doxywikiprj'. It is recommended to protect it. This is formatted table so to speak doxywiki projects.

This table gives all the information that this extension need to generate articles and access for general navigation, additional descriptions, etc.. From here you create the overall index.

Mediawiki:Doxywikiprj format:

Continuing the example:

myproject,My Project Title 1.0,/path/to/output/dir/wiki,/home/dev/src/,en,alpha,My Project Long Description. other,Other 4.2,/path/to/other/wiki,/home/other/src/,en,alpha,The other one.

For each line in this paper, we considered a project. Each line is divided into 7 columns separated by, (comma).

Meaning of columns:


 * 1) Name: the same name that was assigned in WIKI_PROJECT has to do with the indices.
 * 2) Title: The name used in the index and navigation. Short.
 * 3) Pathwiki: the path where files are located. Wiki
 * 4) Pathsrc: the path to the source code (still not used)
 * 5) Lang: the language is written documentation. (still not used)
 * 6) State: State of the documentation (still not used)
 * 7) Longdesc: Space for a detailed description.

Once recorded this page to access the page http://.../Special:DOXYWIKI and ready.

Enjoy!