Nós nos esforçamos bastante para fazer com que a documentação do Django seja útil, de fácil leitura e tão completa quanto possível. Aqui vão algumas dicas de como aproveitá-la da melhor maneira possível, junto com algumas orientações de uso.
(Sim, essa é a documentação sobre a documentação. Fique certo de que não temos planos para escrever um documento sobre como ler o documento sobre a documentação.)
Como os códigos base do Django são desenvolvidos e melhorados diariamente, nossa documentação está melhorando de forma consistente. Nós melhoramos nossa documentação por vários motivos:
- para fazer correções de conteúdo, como correções gramaticias ou de digitação;
- para adicionar informações e ou exemplos a seções existentes que precisam ser expandidas;
- para documentar funcionalidades Django que ainda não estão documentadas (A lista destas funcionalidades está diminuindo, mas ela ainda existe);
- para adicionar documentação de novas funcionalidades assim que elas são adicionadas ou assim que a API do Django muda.
A documentação do Django é mantida no mesmo sistema de controle do código-fonte. Ela reside em django/trunk/docs de nosso servidor Subversion. Cada documento é um arquivo texto separado que cobre um único e específico tópico, como o framework "generic views" ou como construir um modelo de banco de dados.
Você pode ler a documentação do Django de vários modos. Ela está, em ordem de preferência:
A versão mais nova da documentação do Django (em inglês) fica em http://www.djangoproject.com/documentation/. Essas páginas HTML são geradas automaticamente à partir dos arquivos texto no controle de versão. Isso significa que elas refletem o "mais novo e o melhor" do Django -- contêm as mais novas correções e adições e discutem as mais novas funcionalidades do Django, que talvez só estejam disponíveis na versão em desenvolvimento. (Dê uma olhada em "Diferenças entre as versões", a seguir.)
Nós te encorajamos a ajudar na melhoria dos documentos através do envio de alterações, correções e sugestões pelo sistema de tickets da documentação oficinal ou da tradução para o português. Os desenvolvedores do Django monitoram constantemente o sistema de tickets e usam o seu retorno (feedback) para melhorar a documentação para todos.
Observe, entretanto, que os tickets devem estar relacionados explicitamente com a documentação e não servir de meio de contato para suporte técnico. Se você precisa de alguma configuração específica do Django, tente pedir ajudar nas listas django-users, django-brasil, ou nos canais IRC #django e #django-br.
Para uma leitura offline, ou por simples conveniência, você pode ler a documentação do Django em texto puro.
Se você estiver usando uma versão oficial do Django, repare que o arquivo zipado (tarball) do framework contém um diretório docs/ contendo toda a documentação desta versão.
Se você estiver usando a versão em desenvolvimento do Django (também conhecida como versão "trunk" do Subversion), perceba que o diretório docs/ contêm toda a documentação. Você pode dar um svn update, da mesma forma que você dá um svn update no código Python para ter as últimas modificações.
Você pode obter a versão mais nova da documentação no Subversion do Django utilizando este comando shell:
svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs
Uma forma low-tech de tirar proveito da documentação em texto é usar o utilitário Unix grep para procurar por uma frase em toda documentação. Por exemplo, isso irá mostrar todas as ocorrências da frase "edit_inline" em qualquer documento do Django:
grep edit_inline /path/to/django/docs/*.txt
Os arquivos texto da documentação são escritos em formato ReST (ReStructured Text). Isso significa que eles são fáceis de ler e também são formatados de modo que facilitará convertê-los em outros formatos, como o HTML. Se você tiver a biblioteca reStructuredText instalada, você pode usar 'rst2html' para gerar seus próprios arquivos HTML.
Como mencionado anteriormente, a documentação no nosso repositório Subversion contém as "mais novas e melhores" alterações e adições. Estas alterações constantemente contém a documentação de novas funcionalidades adicionadas à versão em desenvolvimento do Django -- a versão Subversion ("trunk") do Django. Por isso, é importante prestar atenção à nossa política de manter a documentação das várias versões do framework.
Nós seguimos a seguinte política:
- a versão principal da documentação, em djangoproject.com, é uma versão HTML dos últimos documentos no Subversion. Esta documentação corresponde a última versão oficial do Django, mais qualquer funcionalidades que nós adicionamos ou alteramos no framework desde o lançamento da ultima versão.
- À medida que nós adicionamos funcionalidades à versão em desenvolvimento do Django, nós tentamos atualizar a documentação na mesma transação commit do Subversion.
- Para diferenciar as alterações/adições na documentação, nós usamos a frase New in Django development version (ou, nas traduções, Novo na versão de desenvolvimento do Django). Na prática, isso significa que a versão atual disponibilizada em djangoproject.com pode ser usada por usuários tanto da última versão lançada quanto da versão em desenvolvimento.
- A documentação de uma versão em particular do Django é "congelada" após ela ter sido oficialmente lançada. Ela se mantém como uma foto dos documentos no momento do lançamento. Nós abriremos exceções à essa regra em casos de alterações de seguranças retroativas ou alguma outra alteração retroativa. Uma vez que a documentação é congelada, nós adicionaremos uma nota no topo de cada documento congelado dizendo "These docs are frozen for Django version XXX" (ou, "Esses documentos estão congelados para a versão XXX do Django").
- A página da documentação principal inclui links para a documentação de todas as versões anteriores.
Hospedado por PyTown.com. Django Brasil é a comunidade brasileira de usuários do framework web Django. Django é uma marca registrada de Lawrence Journal-World.