Mr. Marcelo Babosa

my personal blog to fedora, programing, virtualization, linux, security and much more...
Posts I Like

Ontem em um formato de bate papo gravamos um hangout sobre o release notes do Fedora 20 junto aos amigos da Sys Squad, conseguimos abordar algumas das principais novidades deste novo release e acredito que muitos usuários que gostam de linux vão curtir este material: 

Um Feliz Natal a todos e um próspero ano novo!

    Neste final de semana estive em Santa Catarina para o IV Encontro TecLand, onde ministrei duas palestras junto com o amigo Fábio Olivé, na primeira falamos sobre “O Poder do Fedora ARM" onde conseguimos contar um pouco de como o Fedora tem trabalhado duro para suportar a nova arquitetura ARM. Na segunda apresentamos a palestra "Virtualizando com o oVirt" onde foi possível esclarecer muitas dúvidas como também mostrar o oVirt rodando sob o Fedora 20 com o recurso NESTED habilitado.

   Em ambas as palestras consegui observar algo que realmente anima quem se doa para um projeto open source, o brilho nos olhos da galera mais nova, foi realmente impressionante ver tanta gente sedenta por conhecimento e com tanta vontade de participar e ajudar e neste espírito acredito que tanto eu como o Fábio conseguimos cativar muitos novos colegas para o Fedora como também para o oVirt.

   Quando fui convidado pelo Álisson a participar do evento não imaginava o quanto este seria organizado e produtivo e isto se deve muito ao trabalho dele e da organização junto a UNC, parabéns a todos!!!

   Além do evento foi muito legal poder conhecer duas cidades tão receptivas, limpas e organizadas como Chapecó e Concórdia, sem contar poder estar junto dos amigos é sempre muito gratificante, senti-me em casa e já estou com saudade de ver a Marina(filha do Fábio) chamando-me de TIO Marcelo :)

Primeiramente gostaria de agradecer a todos que estiveram presentes no Hangout de hoje foram quase 70 pessoas confirmadas no evento e em muitos momentos estivemos com mais de 30 pessoas no Youtube vendo o evento e mais o limite preenchido de 10 pessoas no Hangout. 

Conforme comentei vou repassar alguns links que servem de referência sobre os temas que abordamos no Hangout:

Para quem não pode acompanhar o Hangout de hoje segue o link para visualizar novamente:

image

Mês passado, em uma thread da lista de usuários do oVirt, recebi o convite do Dave Neary, para criarmos uma lista de discução sobre o oVirt em português, devido ao grande número de usuários brasileiros que vem aderindo ao projeto, juntamente com os amigos Amador Pahim Douglas Landgraf damos start neste novo ambiente especial para quem fala a língua portuguesa.

A lista esta comemorando o seu primeiro mês de existência a muitas dúvidas, dicas, sugestões, já foram tratadas, assim gostaria de aproveitar e convidar os leitores deste blog, que sentem uma simpatia pelo projeto oVirt, que se juntem a nós, pois através deste ambiente podemos discutir claramente todas as questões que envolvem o projeto, sempre é mais fácil falarmos em nossa língua nativa, sendo assim fica o convite e um bem vindos a todos:

http://lists.ovirt.org/mailman/listinfo/users-pt

Muitas vezes estamos em eventos, clientes e em alguns casos estamos simplesmente com problemas de acesso a internet, sejam estes restrições ou erros das operadoras, logo não é produtivo guardarmos toda nossa documentação de base de conhecimento apenas na nuvem, podemos precisar daquela pequena informação que em outro momento estava ali na nossa frente e devido a estes incidentes estar fora de alcance, sendo assim resolvi criar este post para mostrar como resolvi este problema.

Algumas opções para solucionar este caso eram evidentes a primeira vista, porém custosas em termos de manutenção e uso de recursos, sendo assim listo elas:

image

MediaWiki

Muito usada por diversos projetos, porém além de necessitar de um servidor web, necessita do interpretador da líguagem PHP e seus diversos pré-requisitos além de um banco de dados, algo que iria gerar um custo de manutenção e gestão muito alto em meu caso, lembrando que preciso de algo extremamente simples e leve. http://www.mediawiki.org 

 

image

DokuWiki

Quando visualizei este projeto pensei comigo: “Achei…” porém testando e observando como ele trabalhava ainda não concordei que esta seria uma boa opção, pois mesmo ele não tendo a necessidade de um banco de dados ainda continuava todas as questões relacionadas ao PHP e a necessidade de um servidor web. http://www.dokuwiki.org

 

Anlisei também outros projetos, porém não vou citá-los aqui tendo em vista que coincidem com os problemas do MediaWiki e/ou com os do DokuWiki;

 

image

A solução Sphinx-doc

Após muito procurar percebi que inúmeros projetos, onde seguidamente buscava informação, utilizam o Sphinx-doc como sua base oficial de documentação e pensei comigo: “Vamos testar este…”

Simplesmente foi a solulção que adotei, não somente por ele atender aos meus requisitos inciais: extremamente simples e leve, mas também por este ser feito em Python e estar totalmente portado e funcional no Fedora 19, sistema que utilizo em meu laptop.

Para minha surpresa o Sphinx-doc fez o que eu precisa e muito mais, logo repasso as minhas dicas:

Instalação:

Para quem usa o Fedora 19 é muito simples:

# yum install -y python-sphinx-doc

Configuração:

Agora vamos escolher um diretório onde armazenar nossa base de conhecimento ou Wiki interna, como alguns gostam de chamar, no meu caso criei um diretório dentro de meu $HOME para armazenar meus documentos: /home/marcelo.barbosa/MyWiki/

Para configurarmos usarmos o comando:

$ sphinx-quickstart

Welcome to the Sphinx 1.1.3 quickstart utility.

Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets).

Enter the root path for documentation.

> Root path for the documentation [.]: /home/marcelo.barbosa/MyWiki/

You have two options for placing the build directory for Sphinx output.

Either, you use a directory “_build” within the root path, or you separate

"source" and "build" directories within the root path.

> Separate source and build directories (y/N) [n]: y

Inside the root directory, two more directories will be created; “_templates”

for custom HTML templates and “_static” for custom stylesheets and other static

files. You can enter another prefix (such as “.”) to replace the underscore.

> Name prefix for templates and static dir [_]: 

The project name will occur in several places in the built documentation.

> Project name: MyWiki

> Author name(s): firemanxbr

Sphinx has the notion of a “version” and a “release” for the

software. Each version can have multiple releases. For example, for

Python the version is something like 2.5 or 3.0, while the release is

something like 2.5.1 or 3.0a1.  If you don’t need this dual structure,

just set both to the same value.

> Project version: 0.1

> Project release [0.1]:   

The file name suffix for source files. Commonly, this is either “.txt”

or “.rst”.  Only files with this suffix are considered documents.

> Source file suffix [.rst]: 

One document is special in that it is considered the top node of the

"contents tree", that is, it is the root of the hierarchical structure

of the documents. Normally, this is “index”, but if your “index”

document is a custom template, you can also set this to another filename.

> Name of your master document (without suffix) [index]: 

Sphinx can also add configuration for epub output:

> Do you want to use the epub builder (y/N) [n]: 

Please indicate if you want to use one of the following Sphinx extensions:

> autodoc: automatically insert docstrings from modules (y/N) [n]: 

> doctest: automatically test code snippets in doctest blocks (y/N) [n]: 

> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y

> 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]: 

> ifconfig: conditional inclusion of content based on config values (y/N) [n]: 

> viewcode: include links to the source code of documented Python objects (y/N) [n]: 

A Makefile and a Windows command file can be generated for you so that you

only have to run e.g. `make html’ instead of invoking sphinx-build directly.

> Create Makefile? (Y/n) [y]: 

> Create Windows command file? (Y/n) [y]: 

Creating file /home/marcelo.barbosa/MyWiki/source/conf.py.

Creating file /home/marcelo.barbosa/MyWiki/source/index.rst.

Creating file /home/marcelo.barbosa/MyWiki/Makefile.

Creating file /home/marcelo.barbosa/MyWiki/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /home/marcelo.barbosa/MyWiki/source/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.

Como podem perceber deixei em “NEGRITO" todas as respostas da minha configuração. Após visualizamos que o Sphinx-doc gerou alguns diretórios e arquivos, lembrando que o ele é um gerador de documentos, logo toda a informação fica em html, css e java script, dando toda a portabilidade, simplicidade e leveza que citei como minha necessidade base.

$ ls /home/marcelo.barbosa/MyWiki/

build  make.bat  Makefile  source

Como citei o Sphinx-doc gera todo o resultado final logo o diretório “build" irá armazenar todos os arquivos necessários para visualizar a minha base de documentação e o "source" contém apenas os arquivos usados para essa geração, sendo assim vamos criar nossos primeiros documentos para rapidamente vermos o resultado.

Vamos editar o arquivo: index.srt dentro de source:

.. MyWiki documentation master file, created by

   sphinx-quickstart on Mon Jul 15 15:18:24 2013.

   You can adapt this file completely to your liking, but it should at least

   contain the root `toctree` directive.

Welcome to MyWiki’s documentation!

==================================

Contents:

.. toctree::

   :maxdepth: 2

 

   english

   packages

   packaging

Indices and tables

==================

* :ref:`genindex`

* :ref:`modindex`

* :ref:`search`

Este arquivo contém as chamadas para os documentos que irei criar logo precisamos respeitar uma linha de espaço entre as opções acima de meus novos arquivos(em NEGRITO), e como tudo em Python também devemos respeitar a identação dos meus arquivos perante as opções acima, mais informações em: 

http://pythonhosted.org/an_example_pypi_project/sphinx.html

Neste link também contém diversas informações de como criar os arquivos que foram citados no arquivo: index.srt

Vou mostrar apenas um exemplo simples a fim de não nos concentrarmos tanto na criação de arquivos, algo muito simples e que já temos uma boa referência acima, exemplo: packages.rst

Packages in Fedora Project

=============================

`My packages <https://admin.fedoraproject.org/pkgdb/users/packages/firemanxbr>`_

gists

——-

`Fedora packages gists <https://apps.fedoraproject.org/packages/gists>`_

`Source gists <https://github.com/jdevesa/gists>`_

`Spec gists <https://apps.fedoraproject.org/packages/gists/sources/spec/>`_

Version: 0.4.5-3

python-martian

———————

`Fedora packages python-martian <https://apps.fedoraproject.org/packages/python-martian>`_

`Source python-martian <https://pypi.python.org/pypi/martian>`_

`Spec python-martian <https://apps.fedoraproject.org/packages/python-martian/sources/spec/>`_

Version: 0.14-1

quotatool

————-

`Fedora PKGDB quotatool <https://admin.fedoraproject.org/pkgdb/acls/name/quotatool>`_

in development…

Version: 1.6.2-1

zbar

——

`Fedora packages zbar <https://apps.fedoraproject.org/packages/zbar>`_

`Source zbar <http://zbar.sourceforge.net/>`_

`Spec zbar <https://apps.fedoraproject.org/packages/zbar/sources/spec/>`_

Version: 0.10-17

Como podem perceber é bem simples e eu costumo usar o “vim" para criar toda e qualquer documentação que desejo, após apenas rodo este comando dentro de meu diretório do Sphinx-doc:

$ make html

sphinx-build -b html -d build/doctrees   source build/html

Running Sphinx v1.1.3

loading pickled environment… done

building [html]: targets for 1 source files that are out of date

updating environment: 0 added, 1 changed, 0 removed

reading sources… [100%] packages                                  

looking for now-outdated files… none found

pickling environment… done

checking consistency… done

preparing documents… done

writing output… [100%] packages                                      

writing additional files… genindex search

copying static files… done

dumping search index… done

dumping object inventory… done

build succeeded.

Build finished. The HTML pages are in build/html.

Agora você pode utilizar um servidor web ou mesmo abrir os arquivos diretamente em seu browser preferido.

image

Acredito que até aqui conseguimos mostrar um bom potencial para o uso do Sphinx-doc, porém ele faz muito mais do que mostrei, ele consegue fazer auto-geração de documentação para códigos em Python, algo muito interesante para quem tem projetos nesta línguagem como eu, mas este será um tema para outro post.