EVO X

Guia de Escritura de Documentacion

Guia de Escritura de Documentacion

Esta guia describe las mejores practicas para escribir y mantener la documentacion en el codigo fuente y los archivos complementarios.

Documentacion en el Codigo (Docstrings)

Los docstrings son esenciales para entender el proposito, uso y comportamiento de tu codigo. Por favor, sigue las siguientes convenciones:

Reglas Generales

  • Documenta todas las clases, metodos y funciones publicas usando docstrings.
  • Usa docstrings de estilo Sphinx.
  • No incluyas tipos de parametros en el docstring; se espera que se declaren en la firma de la funcion usando anotaciones de tipo.

Formato y Directivas

Usa las siguientes directivas para describir diferentes elementos:

  • :param <nombre>: — Describe un parametro.
  • :return: — Describe el valor de retorno.
  • :raises <excepcion>: — Describe las excepciones que la funcion podria lanzar.

Ejemplo

def add(a: int, b: int) -> int:
    """
    Add two integers.

    :param a: The first integer.
    :param b: The second integer.
    :return: The sum of the two integers.
    :raises ValueError: If either input is not an integer.
    """
    if not isinstance(a, int) or not isinstance(b, int):
        raise ValueError("Inputs must be integers.")
    return a + b

Documentacion Externa (Directorio docs/)

Toda la documentacion a nivel de proyecto se encuentra en el directorio docs/. Estos documentos apoyan tanto a usuarios como a desarrolladores proporcionando guias, ejemplos y referencias.

Formato

  • Usa Markdown (.md) o Jupyter Notebooks (.ipynb) para la documentacion.
  • Markdown es preferido para contenido narrativo y documentacion estatica.
  • Usa Jupyter Notebooks para contenido ejecutable e interactivo (por ejemplo, tutoriales o demos).

Directrices para Jupyter Notebooks

  • Asegurate de que todos los notebooks sean completamente ejecutables.
  • Siempre ejecuta todas las celdas y guarda la salida antes de hacer commit.
  • Nuestro entorno de CI/CD no soporta ejecucion con GPU, por lo que los notebooks deben ser pre-ejecutados localmente.

Directivas de Markdown y Notebooks

Usa los siguientes patrones para formato enriquecido:

  • [nombre](#ref) — Referencia cruzada interna, por ejemplo, [ModuleBase](#evox.core.module.ModuleBase) o [ModuleBase](#ModuleBase)
  • ![Texto Alt](ruta) — Insertar imagenes, por ejemplo, ![Module base](/_static/modulebase.png)

Traduccion

La documentacion soporta contenido multilingue. Sigue los pasos a continuacion para actualizar o generar traducciones.

Actualizar Traducciones (por ejemplo, para zh_CN)

cd docs
make gettext
sphinx-intl update -p build/gettext -l zh_CN
cd ..
python docs/fix_output.py
← Volver a la documentación