Cómo editar Ayuda y contribuir¶
Nota
Página para revisión.
Las correcciones, omisiones y retroalimentación son bienvenidas, iain at browndouglas dot com . 28 de noviembre 2013.
Ayuda muestra documentación de Sugar y el portátil XO.
Esta versión de ayuda contiene todos los archivos de código fuente y las imágenes, y ahora permite ref:View source. Estos archivos se pueden editar y ver en Ayuda. La ayuda es ahora capaz de producir nuevas páginas para Ayuda, o hacer documentación completamente nueva.
Esta página tiene como objetivo mostrar cómo escribir documentación atractiva, que, si los usuarios compartir su trabajo, podría ser utilizado para mejorar la Ayuda. Para contribuir sólo necesitas:
Crear un entorno de desarrollo
Hacer los cambios
Contribuir con los cambios
Crear un entorno de desarrollo¶
XO Help.xo 17 ya incluye los archivos de fuentes listos para usar.
Alternativamente, puedes utilizar git para obtener la Actividad Ayuda con los fuentes más recientes incluidos. Si tienes la actividad de ayuda ya instalado, desinstalala primero. Generalmente una Actividad se desinstala desde la Vista Hogar, en la VIsta de Lista, mediante la selección de la Actividad y pulsando Borrar. Dónde Borrar no está disponible, es necesario eliminar la actividad `` Ayuda. `` de la carpeta ~/Activities.
La siguiente guía supone que tu haz hecho git clone desde su directorio principal. Este comando recoger todos los recursos necesarios.
git clone git@github.com:godiard/help-activity.git
Se puede instalar en el entorno de desarrollo de Sugar haciendo:
cd help-activity
./setup.py dev
Necesita tener un ambiente de Sugar completa para correr “setup.py dev” si tienes un error en tu sistema, trata de ejecutarlo en la Actividad Terminal.
y, cuando estes listo, llenar tus páginas de Ayuda
make html
Puedes modificar cualquier archivo .rst primero en ~ /help-activity/source/ o las imágenes en su directorio ~/help-activity/source/images/.
Para crear los nuevos archivos HTML sólo necesitas hacer:
cd help-activity
make html
Si ves un error que indica que el HTML no se pudo construir, la causa más probable es que falte python-sphinx.
Para solucionar este problema, en la Actividad Terminal (o cualquier emulador de terminal) haz como root,
yum install python-sphinx
o en derivados de Debian o Ubuntu,
sudo apt-get install python-sphinx
En Sugar no es necesario reiniciar Ayuda para ver los cambios después de ejecutar make html, basta con hacer clic con el botón secundario del ratón y selecciona recarga.
En cualquier otro ambiente distinto a Sugar, Linux el comando `` git clone git@github.com:godiard/help-activity.git`` funciona para descargar el código fuente,``./setup.py dev`` debe omitirse, y la salida de `` make html`` está en ~/help-activity/html, y se muestra al abrir `` ~/help-activity/html/index.html`` en un navegador.
¿Qué pasa si rompo ayuda?¶
En Sugar no se puede romper Ayuda. Si comienzas a seguir estas instrucciones y te pierdes o cometes un error, y Ayuda no se muestra correctamente, no debes preocuparte.
Primero haz una copia de seguridad de los archivos .rst que ya haz hecho, a continuación, visita `ASLO <http://activities.sugarlabs.org> `_ con Navegar, búsca Ayuda y descarga e instala una nueva copia de XO Ayuda.
Alternativamente, los usuarios experimentados pueden hacer una copia de seguridad. del .xo antes de comenzar a trabajar haciendo:
./setup.py dist_xo
Esto creará un directorio dist y en el interior, un. archivo .xo.
Tutorial 0 - Explorar sistema de archivos¶
En Navegar y algunos otros navegadores si escribes
file:///
en la barra de direcciones, estarás navegando la raíz del sistema de archivos.
Ahora muevete progresivamente a través
file:///home
file:///home/your-username
file:///home/your-username/help-activity
file:///home/your-username/help-activity/source
Ahora eres capaz de abrir e inspeccionar cualquiera de los archivos fuentes .rst en forma segura.
Podemos retroceder de nuevo y llegar
file:///home/your-username/help-activity/html
y luego seleccionar y mostrar cualquiera de los archivos HTML de salida.
En esta página se utiliza la convención de llamar /home/tu-nombre/help-activity/source por el más corto, ~/help-actividad/source.
Orientación¶
Fuentes
Las dos carpetas de origen que miramos se llenan inicialmente por la descarga de Ayuda.
El directorio ~/help-activity/source/ contiene los archivos de texto que vamos a alterar en esta guía.
El directorio ~/help-activity/images/ contiene todas las imágenes que se utilizan en las distintas páginas de Ayuda. Puedes agregar archivos de imagenes a esta carpeta, y si están vinculados a documentos, se mostrarán en la salida de la orden make html.
En Sugar usted tiene la capacidad de inspeccionar los archivos de origen de forma segura, utilizando el boton Ver código fuente en el icono Ayuda en el Marco.
La página clave en la navegación de Ayuda es la página de índice o de contenidos. En la carpeta ``~ /help-activity/source// ` el archivo, ` índex. rst es el documento de texto que proporciona automáticamente los enlaces a todas las otras páginas de la carpeta de origen.
Salida
Las páginas mostradas en la Ayuda son el resultado del comando make html. Los archivos están en la carpeta ~/help-activity/html/.
También forman parte de la salida de la orden make html los archivos de ~/help-activity/doctrees/ ``. El papel de los `` archivos ``all_files.doctree es conseguir la interconexión de todas las páginas HTML dentro de las reglas del software subyacente.
Dependiendo de la configuración de su instalación puede haber un número de otras carpetas presentes en el directorio ~/help-activity/html/ carpeta (por ejemplo _sources, _static, e _images). Estos son también archivos de salida, podrían ser considerados como carpetas ocultas, y no deben ser editados.
Hacer los cambios¶
Puedes escribir una página en texto simple, tal vez con algunas imágenes explicativas o fotografías de pantalla. Las instantáneas de pantallas se hacen en Sugar desde el teclado, pulsando la tecla “Alt” y 1.
La página Escribiendo en reStructuredText da una orientación sobre las características del lenguaje de marcas que utilizamos. No te preocupes con características complejas, texto plano, simplemente escrito será de mayor utilidad para los nuevos estudiantes.
Tendrás tus propias ideas acerca de lo que te gustaría cambiar y contribuir. Cuando expliques algo, que hayas tenido problemas para aprender, es probable que sea de utilidad para otros. Al ver tu trabajo publicado da una gran alegría!
Aquí hay algunos ejercicios, que demuestran como realizar cambios, y hacer páginas.
Tutorial 1 - Hacer una página¶
Vamos a hacer una nueva página en reStructuredText. Al principio no estará conectado al índice o página de contenidos, de Ayuda.
Abre un nuevo archivo en cualquier editor de texto.
Guarda el archivo con el nombre de my_first.rst en ~/ help-actividad/source. Escribe algún texto en la página. Con el fin de dar a la página un título ponemos una línea de “=” “signos de igualdad” por encima y por debajo del título como este. Deja una línea de espacio en blanco, a continuación, escribe algún texto. Este es un ejemplo:
=============
My first page
=============
I am going to learn to write a Help page.
Ahora queremos convertir nuestra página de texto en una página atractiva de Ayuda. Abre la Actividad Terminal (o cualquier emulador de terminal) y tipéa,
cd help-activity
make html
Habrá cerca de diez líneas de salida, habrá una mención a los errores. Leer la traza de error, esperan ver una línea de error como la de abajo, pero las dos últimas líneas reportarán un éxito.
~/help-activity/source/my_first.rst:: WARNING: document isn't included in any toctree
...
build succeeded, 3 warnings.
Build finished. The HTML pages are in ./html.
La advertencia, “WARNING: document isn’t included in any toctree” nos está diciendo que el documento no está vinculado al Índice de ayuda aún.
Tutorial 2 solucionará el problema. Ya existe y se puede ver como luce si lo puede encontrar como se describió anteriormente con un navegador en ~/help-activity/html.
Tutorial 2 - Enlace a la página índice¶
Haz una copia de seguridad de tu archivo de índice. Abre Actividad Terminal (o cualquier emulador de terminal) y tipéa,
cd help-activity
cd source
cp index.rst index.rst.ori
Aqui, hemos cambiado al directorio help-activity, cambiado de directorio a source, y copiado index. rst en un nuevo archivo llamado index.rst.ori
Antes de proceder asegúrate de que estas familiarizado con la forma de restaurar el índice desde la copia de seguridad, en caso de que se causara daños en el índice de Ayuda.
Abre ~/help-activity/source/index.rst con un editor de texto. Observa el espacio entre líneas (líneas de espacio en blanco en especial) y guiones. Es muy importantes mantenerlos.
Desplácese hacia abajo en index.rst derecho a la parte inferior de la página. Ponga el cursor en la parte delantera de la última línea. Usando las flechas, verá que el guión es de 4 “espacios”, no es “Tab”.
Ponga el cursor al final de la última línea. Pulse Ingresar, presione la barra espaciadora 4 veces, y escriba el nombre de archivo que utilizó `` my_page.rst``. Utilice “Ingresar” y la barra de espacio para que se copia exactamente la sangría y espaciado de línea que se utiliza en el resto de entradas.
Vuelve a comprobar tus cambios index.rst y guardar los cambios.
Ahora queremos convertir nuestro índice en HTML. Abre la Actividad Terminal (o cualquier emulador de terminal) y tipéa,
cd help-activity
make html
La página de índice recién cambiado se mostrará en la Ayuda, o en su navegador, una vez que vuelva a cargar la página. En Sugar hace clic con el botón secundario y selecciona recarga, o en un navegador que apunta a `` ~/help-activity/html/index.html`` pulse el botón de recarga. En el índice o página de contenidos, el vínculo con la nueva página se puede hacer clic para abrir la página “my_page.html”
Tutorial 3 - Adición de una imagen¶
Abre tu página existente en cualquier editor de texto, o crea y “Títula” una nueva página, y agregala a la parte inferior del índice.
Una imagen que ya está en ~/help-activity/images/ se puede incluir escribiendo esto en tu página.
.. image :: ../images/Help.png
La “línea de referencia” anterior necesita una línea de espacio en blanco, por encima y por debajo de ella.
Puedes agregar un archivo de imagen en formatos .jpg o .png a ~/help-activity/images/. Lo mejor es que la imagen no sea superior a 800 píxeles de ancho. Puede ser difícil de leer imágenes altas. Por esta razón, capturas de pantalla de 600 píxeles de ancho pueden ser un buen compromiso si el contenido es simple.
Si agregas un archivo de imagen my_image.png, hecha en, digamos, Pintar a ~/help-activity/images/, entonces enlazalo en tu página con:
.. image :: ../images/my_image.png
Ahora queremos convertir nuestra página con una imagen en HTML. Abre la Actividad Terminal (o cualquier emulador de terminal) y tipéa,
cd help-activity
make html
La página recién cambiada se mostrará en la Ayuda, o en tu navegador, una vez que vuelvas a cargar la página.
Tutorial 4 - Escribir o mejorar una página de ayuda¶
Decide si deseas hacer una página comenzando de cero, podrías comenzar a escribir sobre un tema del que usted sabes. Alternativamente puedes experimentar con la mejora de una página existente. Podría trabajar en el texto de una página existente (que podría ser esta página) o una página más sencilla.
Abre ~/help-activity/fuente/index.rst.
Pon el cursor al final de la última línea. Pulsa Ingresar, presiona la barra espaciadora 4 veces, e introduce un nuevo nombre de archivo, tal vez, my_second.rst. Utiliza “Ingresar” y la barra de espacio para que se copie exactamente la sangría y espaciado de línea que se utiliza en el resto de las entradas.
Vuelve a comprobar tus cambios index.rst y guardar los cambios.
Abre un nuevo archivo en cualquier editor de texto.
Guarda la página con el nuevo nombre de archivo elegido anteriormente, tal vez, my_second.rst.
Escribe un título como este:
==================
How I changed Help
==================
Introduce el texto y guardar los cambios.
Ahora queremos convertir nuestra página en HTML. Abre Actividad Terminal (o cualquier emulador de terminal) y tipéa,
cd help-activity
make html
La página recién generado se mostrará ahora en la Ayuda, o en tu navegador, una vez que vuelva a cargar la página.
Ahora puedes volver a la página y mejorarla.
Una vez más, escribe los cambios en la versión HTML, con:
cd help-activity
make html
Ahora haz escrito tu primera página mejorada para la Actividad Ayuda. Nos encantaría si pudieras compartir con la comunidad de Sugar!
Contribuir¶
Una vez que estés familiarizado con la edición, la adición de una página, y hacer o mejorar una página de ayuda, podrías hacer una página con la intención de que se publique en la próxima versión de Ayuda.
Puede escribir un tutorial sobre un tema acerca del que tu sepas.
En la próxima versión de la Actividad Ayuda, mejores páginas “Nuevo a Sugar” podrían ser incluidos en el comienzo de Ayuda, como una introducción rápida para los nuevos estudiantes de Sugar. Contribuciones a considerar serían bienvenidas.
Algunas actividades no tienen instrucciones fáciles de encontrar. Si tu puedes escribir incluso una muy breve introducción, podría ser muy útil para otros estudiantes de Sugar.
La página wiki http://wiki.sugarlabs.org/go/Activities/Help/Contribute podría tener algunas ideas sobre las páginas que han sido solicitadas, o en las que otros están trabajando y pudieran apreciar colaboración.
¿Qué hacer con su obra terminada¶
En primer lugar usted puede ponerse en contacto brevemente con gonzalo at laptop dot org por e-mail y decirle lo que le gustaría contribuir. Si se escribe una nueva página, se le puede enviar la página (como my_page.rst) como un archivo adjunto a un e-mail explicando brevemente lo que se adjunta. Si nuevas imágenes están vinculadas a la página, envíalas también.
Si tu haz mejorado una página, el método preferido es el de enviar como un “parche”.
Tutorial 5 - generar un parche¶
Digamos que tu decides trabajar en la página de ayuda, “Cambiando Actividades” . Puedes hacer una copia de seguridad de que la página antes de empezar. Abre la Actividad Terminal (o cualquier emulador de terminal) y tipéa,
cd help-activity
cd source
cp switching_activities.rst switching_activities.rst.ori
Aqui, hemos cambiado el directorio help-activity, cambiado al directorio de fuentes, y copiado switching_activities.rst en un nuevo archivo llamado switching_activities.rst.ori
Realiza los cambios en switching_activities.rst. Guarda los cambios con regularidad, y comprobar mediante la ejecución del comando make html que se muestre la página correctamente. Una vez que estés satisfecho con tu trabajo, puedes generar un parche asi:
cd help-activity
cd source
diff -u switching_activities.rst.ori switching_activities.rst > switching_activities.patch
El parche se puede enviar como archivo adjunto de correo electrónico.
Para obtener más información, en la Actividad Terminal (o cualquier emulador de terminal) tipéa,
man diff
y
man patch
Para leer más¶
Para obtener ayuda más completa sobre reStructuredText:
ReStructuredText rápida, http://docutils.sourceforge.net/docs/user/rst/, es una hoja de trucos para reStructuredText.
“Directivas reStructuredText” http://docutils.sourceforge.net/docs/ref/rst/directives.html por David Goodger, Marzo 2013.
Sphinx reStructuredText Básico, http://sphinx-doc.org/rest.html, una breve introducción a reStructuredText conceptos y sintaxis.
Página de inicio Sphinx, http://sphinx-doc.org/index.html.
Otro tutorial, http://matplotlib.org/sampledoc/.