SoundRevolution Documentacion Documentation

SoundRevolution Documentacion
Documentation
Publicación 0.1
Leonel Franchelli
23 de August de 2014
Índice general
1. Aprendiendo a documentar
1.1. Creando un proyecto de documentacion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2. Empezando a documentar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3. Estandares y estructura del proyecto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
3
4
5
2. Aprendiendo a documentar
9
3. Bundles
3.1. Bundles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2. Bundles de terceros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
11
11
4. Indice
13
I
II
SoundRevolution Documentacion Documentation, Publicación 0.1
Bienvenidos a la documentacion para el proyecto, aqui encontraran documentacion tanto para el proyecto como tips y
ayudas nuestros.
Índice general
1
SoundRevolution Documentacion Documentation, Publicación 0.1
2
Índice general
CAPÍTULO 1
Aprendiendo a documentar
1.1 Creando un proyecto de documentacion
En este capitulo se explica como crear un proyecto de documentacion desde cero.
Atención: Si no les intereza como crear un proyecto, sino simplemente documentar vayan al capitulo: Empezando
a documentar
1.1.1 Librerias necesarias para crear un proyecto nuevo:
Sphix
VirtualEnvironment
Pip
Easy_install
1.1.2 Instalando las librerias
Lo que tienen que hacer es lo siguiente:
1. Bajar la libreria easy_install de python
wget https://bootstrap.pypa.io/ez_setup.py -O - | python
2. Instalar pip
pip install virtualenv
3. Una vez instalado el virtualenv, creamos un entorno virtual donde vamos a descargar las librerias necesarias (
en este caso solamente sphinx )
virtualenv nombreEnterno
4. Activamos el entorno virtual
#Entramos al entorno
cd nombreEntorno
#Lo activamos
source bin/activate
3
SoundRevolution Documentacion Documentation, Publicación 0.1
Se van a dar cuenta que esta activado porque aparece “(nombreEntorno) ...”
5. Le instalamos la libreria Sphinx al entorno que creamos
pip install sphinx
Con estos 5 pasos ya vamos a tener todas las dependencias de la libreria y la libreria instaladas en el entorno virtual
1.1.3 Creando el proyecto de documentacion
Estando dentro del entorno, van a cualquier carpeta del sistema de archivos por ejemplo el home
cd ~
Crean una carpeta nueva
mkdir ejemploDocs
Lo unico que hay que ingresar ahora es el siguiente comando para crear el proyecto
sphinx-quickstart
El comando los va a llevar a un wizard donde les va a hacer algunas preguntas para crear el proyecto
Las unicas que tienen que modificar son:
Separate source and build directories (y/N) [n] , pongan “y”
Name prefix for templates and static dir [_] , pongan “n” si es que quieren usar el template de readthedocs
Would you like to automatically insert ... , pongan “y”
Una vez que terminen de responder las preguntas se les genera una estructura de directorios
Makefile ,build, make.bat, source
Lo que pueden hacer es borrar make.bat si quieren .., luego borrar el directorio build y copiar todo lo que contenga
el directorio source un nivel mas arriba ”../”.
Entonces les va a quedar solamente Makefile y los archivos que tenia el directorio source.
Ya con esto pueden empezar a documentar editando el archivo index.rst
1.2 Empezando a documentar
Importante: Es importante que lean desde este capitulo en adelante ya que se definen estandares que vamos a usar
para documentar.
Para poder documentar mas facil es recomendable instalar el siguiente plugin de sublime-text:
Plugin
En este link podran encontrar bastante documentacion del formato “Sphinx”
Tutorial
Este ultimo es un video que muestra como usar el plugin, muy util.
Truco: El documento tiene que estar en sintaxis restructuredText ( lo cambian con CTRL+ SHIFT + P ) escriben
“restruc” y ya les salta la opcion para usar los “shortcuts”, deben apretar TAB luego de una palabra clave por ejemplo
h1 + TAB
4
Capítulo 1. Aprendiendo a documentar
SoundRevolution Documentacion Documentation, Publicación 0.1
Tutoriales sobre el formato del codigo:
http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
http://sphinx-doc.org/rest.html
http://documentation-style-guide-sphinx.readthedocs.org/en/latest/style-guide.html
Una vez que hayan visto la documentacion y el video ya pueden empezar a documentar basicamente.
1.2.1 Repositorio
El repositorio que vamos a usar es el siguiente
https://bitbucket.org/soundrevolutionTeam/documentacion
Atención: Por favor no anden pasando el repositorio ya que es de acceso publico, ya que sino readthedocs no lo
podria descargar
1.2.2 Forma de trabajar
Se hacen un pull del repositorio en cualquier lugar del sistema de archivos, agregan lo que quieran, hacen un commit
luego un push, y automaticamente readthedocs construye la nueva documentacion, esto es posible gracias a un hook
entre bitbucket y readthedocs que le avisa cuando se hace un push.
En el proximo capitulo vamos a explicar los estandares del proyecto de documentacion mencionado en el repo.
1.3 Estandares y estructura del proyecto
Como pueden ver en el repositorio mencionado en el capitulo anterior, hay un archivo index.rst y una carpeta documentando .
Hay un carpeta por cada seccion de la documentacion como pueden ver por ejemplo documentando
La carpeta contiene un map.rst.inc y un index.rst obligatoriamente
En map.rst.inc hay un mapeo de todos los archivos que contiene la carpeta
* :doc:‘/documentando/crear-proyecto‘
* :doc:‘/documentando/empezando‘
* :doc:‘/documentando/estandares‘
En index.rst hay un toctree el cual sirve para “indexar” los capitulos de la seccion, y se incluye el archivo
map.rst.inc el cual contiene links a los capitulos.
Aprendiendo a documentar
========================
.. toctree::
:hidden:
crear-proyecto
empezando
estandares
1.3. Estandares y estructura del proyecto
5
SoundRevolution Documentacion Documentation, Publicación 0.1
.. include:: /documentando/map.rst.inc
En cada capitulo de la seccion lo primero que se tiene que definir es el index, para decirle a sphinx que es un
indice
.. index::
single: Empezando a documentar
Esto crea un indice con el titulo “Empezando a documentar”
Por ultimo en el index.rst principal se incluyen las secciones
.. SoundRevolution Documentacion documentation master file, created by
sphinx-quickstart on Sun Jul 13 03:07:40 2014.
You can adapt this file completely to your liking, but it should at least
contain the root ‘toctree‘ directive.
SoundRevolution
===============
Bienvenidos a la documentacion para el proyecto, aqui encontraran documentacion tanto para el pr
.. toctree::
:hidden:
documentando/index
Aprendiendo a documentar
-----------------------.. include:: /documentando/map.rst.inc
Bundles
===============
Documentacion de los diferentes bundles que vamos a usar en el proyecto.
.. toctree::
:hidden:
bundles/index
Bundles de terceros
-----------------------.. include:: /bundles/map.rst.inc
Indice
================
* :ref:‘genindex‘
Como pueden ver se incluye la seccion por ejemplo Aprendiendo a documentar al proyecto de la siguiente manera
Se le dice a Sphinx donde buscar los indices linkeando un toctree al index de la seccion en el caso de documentacion
es documentando/index
Luego se incluye el map.rst.inc el cual contiene links a los distintos capitulos de la seccion .. include::
/documentando/map.rst.inc
6
Capítulo 1. Aprendiendo a documentar
SoundRevolution Documentacion Documentation, Publicación 0.1
Nota: Como pueden ver organizar las secciones en carpetas es mucho mas util ya que lo unico que hay que hacer es
agregar el toctree y los indices de la seccion, al index principal, “Es mas modular”
Creando un proyecto de documentacion
Empezando a documentar
Estandares y estructura del proyecto
1.3. Estandares y estructura del proyecto
7
SoundRevolution Documentacion Documentation, Publicación 0.1
8
Capítulo 1. Aprendiendo a documentar
CAPÍTULO 2
Aprendiendo a documentar
Creando un proyecto de documentacion
Empezando a documentar
Estandares y estructura del proyecto
9
SoundRevolution Documentacion Documentation, Publicación 0.1
10
Capítulo 2. Aprendiendo a documentar
CAPÍTULO 3
Bundles
Documentacion de los diferentes bundles que vamos a usar en el proyecto.
3.1 Bundles
/bundles/FixturesBundle
/bundles/AdminGeneratorBundle
3.2 Bundles de terceros
/bundles/FixturesBundle
/bundles/AdminGeneratorBundle
11
SoundRevolution Documentacion Documentation, Publicación 0.1
12
Capítulo 3. Bundles
CAPÍTULO 4
Indice
genindex
13