¿Por qué se creó este manual?

En el pasado, información y recursos relacionados con las Carpentries estaban dispersos en varios sitios de la red. Este manual abarca la información en una manera centralizada sobre cómo gestionar un taller, crear o mantener una lección, participar en el curso de instructores y mucho más.

Muchos miembros de la comunidad han ayudado a la creación de este cuaderno, y así también aceptamos nuevas aportaciones. Ayúdanos a mejorar este recurso comunitario a través de la creación de incidencias (issues) o nuevas contribuciones (a traves de pull requests) en el presente repositorio de GitHub. (Nota: Si deseas ayudar con las traducciones accede a través de transifex).

Compilando el manual

Este sitio está construido utilizando el generador de documentación Sphinx (una herramienta de Python) y el tema Read the Docs para el estilo. (No debe confundirse con readthedocs.io: ¡el sitio no está alojado en readthedocs.io!)

Para obtener más información sobre el uso de Sphinx, consulte la Guía de inicio (sphinx-doc.org) o el Quick Start (readthedocs.io) para obtener una explicación sobre cómo usar Sphinx.

Dependencias requeridas

Para instalar las dependencias requeridas (Sphinx y el tema ReadTheDocs), ejecute el siguiente comando desde el directorio del repositorio para instalar todas las dependencias de Python:

pip install -r requirements.txt 

Después de instalar las dependencias, puede construir el sitio localmente ejecutando el siguiente comando desde el repositorio:

$ make html

Abra el archivo _build / html / index.html para obtener una vista previa del sitio localmente. Python ofrece una forma rápida de ejecutar un servidor web para albergar archivos locales. Ejecute lo siguiente:

$ cd _build/html

# Python 2:
$ python2 -m SimpleHTTPServer

# Python 3:
$ python3 -m http.server

En ambos casos, se ejecutará un servidor web local en el puerto 8000, así que navegue a http://localhost:8000 en su navegador para ver el sitio localmente.

Puede realizar cambios en el contenido del repositorio y volver a ejecutar make html para actualizar el contenido del sitio web. Si tiene problemas con que el sitio no se actualiza, puede eliminar el contenido del directorio _build (que se genera automáticamente) con rm -fr _build/*.

Si se agregan nuevos archivos o carpetas al Manual, será necesario actualizar index.rst para que Sphinx los incluya en el sitio final.

Estructura del Sitio

El nivel raíz index.rst genera las categorías principales y la barra lateral de navegación. Cada subsección es una carpeta en el directorio topic_folders. Cada carpeta dentro del directorio topic_folders tiene su propio archivo index.rst. Estos luego se expanden en las subcategorías en cada directorio.

Dentro del archivo index.rst de cada carpeta, el encabezado de una sección está definido por una cadena de «===» por debajo. Los subtítulos se pueden definir usando «###» en cada archivo de Markdown o por un encabezado con «—» por debajo en el archivo index.rst.

Información Adicional

Este sitio está construido a partir del master branch de este repositorio (carpentries/handbook). Los cambios se pueden observar en vista previa aquí: http://docs-src.carpentries.org/. Los cambios en el sitio real https://docs.carpentries.org/ pueden tardar hasta un día en activarse una vez que los cambios se han enviado a Github, ya que el contenido del sitio está detrás de una CDN (Content Distribution Network o Red de distribución de contenido español) que almacena el contenido en caché.

Si está realizando cambios experimentales en el contenido, asegúrese de hacerlo en un branch que no sea master branch o live branch. Cuando sus cambios estén completos y listos para ser enviados al live site, abra un pull request en carpentries/handbook.

Los borradores se pueden agregar a la carpeta de drafts del repositorio carpentries/userguides (en el master branch) sin dañar nada. Los borradores no se crean para el live site y estos archivos pueden contener información inexacta o desactualizada.