Open main menu

Extension:DoxyWiki

HELP WANTED: I'm looking for someone who wants to continue this extension. [1]

MediaWiki extensions manual
OOjs UI icon advanced.svg
Doxywiki
Release status: beta
DoxyWiki-Screenshot.png
Implementation User interface, Special page , Tag
Description Integrates doxygen into MediaWiki.
Author(s) THE-EYE (Rnrtalk)
Latest version 1.0 (2008-05-13)
License No license specified
Download current revision
Example online example
Translate the DoxyWiki extension if it is available at translatewiki.net
Check usage and version matrix.


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.


Contents

Para que sirve DoxywikiEdit

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?Edit

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 ConfiguracionEdit

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

Descargar doxygen y compilarEdit

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:

# mkdir doxygen-svn; cd doxygen-svn
# svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk
# cd trunk
# ./configure
# make

Instalar el parche doxygen_r999_v9.patchEdit

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.

# pwd
.../doxygen-svn/trunk
# cd src
# patch -p1 </location/of/doxygen_r999_v9.patch
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
# cd ..
# ./configure
# make

Instalar el componente PHP para MediaWikiEdit

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 DocumentadoEdit

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)

# :P
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/

Luego ejecutamos:


# /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 DoxywikiEdit

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 rationaleEdit

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 worksEdit

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 ConfigurationEdit

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

Download and compile doxygenEdit

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

# mkdir doxygen-svn; cd doxygen-svn
# svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk
# cd trunk
# ./configure
# make

Install the patch doxygen_r999_v9.patchEdit

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.

# pwd
.../doxygen-svn/trunk
# cd src
# patch -p1 </location/of/doxygen_r999_v9.patch
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
# cd ..
# ./configure
# make

Install PHP component for MediaWikiEdit

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 codeEdit

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:

# /path/to/doxygen doxyconf.txt

This generates the documentation in fto doxywiki in the folder /path/to/output/dir/wiki/.

Now we need only set up the project ...

Set Doxywiki projectsEdit

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!