Documentación Técnica con Sphinx

Saludos, vamos a hablar y a crear una documentación técnica usando sphinx, lo primero que debemos hacer es instalarlo en nuestra distro, si usas pip te será mucho más fácil hacer la instalación, ejecutando el comando pip install sphinx si, por desgracia usas Windows, no te preocupes también funciona ahí, te dejo este enlace para que veas el proceso de instalación http://sphinx-doc.org/latest/install.html

Una vez instalado debemos ejecutar el siguiente comando para crear el proyecto en el cual vamos a trabajar sphinx-quickstart


> Root path for the documentation [.]:
> Separate source and build directories (y/n) [n]:
> Name prefix for templates and static dir [_]:
> Project name:
> Author name(s):
> Project version:
> Project release [1]:
> Project language [en]:
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> sphinx: link between Sphinx documentation of different projects (y/n):
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> pngmath: include math, rendered as PNG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> config: conditional inclusion of content based on config values (y/n):
> include links to the source code of documented Python objects (y/n):
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:
You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Debes responder esa serie de preguntas referentes a tu proyecto, una vez hecho esto se te crearán las carpetas del mismo y quedará de la siguiente forma

prueba
├── _build
├── conf.py
├── index.rst
├── make.bat
├── Makefile
├── _static
└── _templates

En el index.rst está la definición de nuestro proyecto, ahí colocaremos los archivos .rst para crear la documentación


.. prueba documentation master file, created by
sphinx-quickstart on Tue Jun 2 09:58:20 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to prueba's documentation!
==================================

Contents:

.. toctree::
:maxdepth: 2

intro

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

En la sección “Contents:” van los archivos .rst de nuestro proyecto.

creamos el archivo intro.rst y le damos el siguiente formato:

Introducción
================================
Una breve introducción a nuestro proyecto.

Agregamos el intro al Contents: del archivo index.rst y desde la consola ejecutamos make html, dentro de la carpeta _build quedarán los .html que hemos definido para nuestro proyecto.

Con eso tenemos la forma básica de crear documentación técnica, se puede modificar los temas de nuestro proyecto para darle mayor y mejor apariencia, los por defecto de sphinx están alojados aquí, tu también puedes crear los tuyos siguiendo la guía.

hasta pronto, espero les sea útil y cualquier comentario, duda y/o sugerencia ya saben donde dejarla.

Crear una imagen de nuestros modelos en Django

Hace un tiempo conocí la posibilidad de hacer una imagen con tus modelos de tus apps Django, el proceso es bastante simple y sirve para que veas como estarían quedando relacionados tus apps. Comencemos entonces.

Lo primero es que debes tener instalado
pip install pygraphviz
Una vez instalado debes instalar django_extensions y colocarlo en settings.py, esto puedes hacerlo con el comando
pip install django_extensions

Ahora, simplemente ejecutas
./manage.py graph_models -a -g -o mis_modelos.png

Puedes ejecutar el comando especificando cuales apps mostrar en la imagen con el siguiente comando
./manage.py graph_models app1 app2 app3 -o mis_modelos.png
models

Instalando psycopg2

Esta entrada es para que no se olvide el comando y para ayudarlos a ustedes cuando tengan que usar Python con PostgreSQL (ya que tengo memoria de pez), al grano entonces, debemos instalar lo siguiente:

En el caso de usar Debian/Ubuntu
apt-get install libpq-dev python-dev

Si usas CentOS/Fedora
yum install python-devel postgresql-devel

Una vez instalado podremos instalarlo con el comando

pip install psycopg2

¿Simple, no?, más que una entrada es una receta🙂