O que ler a seguir¶
Então você leu todo o material introdutório e decidiu que você gostaria de continuar a usar Django. Nós apenas arranhamos a superfície nesta introdução (de fato, se você leu cada palavra, você leu aproximadamente 5% de toda a documentação).
E agora?
Bem, nós sempre fomos muito fãs de aprender fazendo. Neste ponto você deve saber o bastante para iniciar um projeto próprio e começar a brincar com ele. Com você precisando aprender novos truques, volte para a documentação.
Nós colocamos muito esforço em fazer a documentação do Django útil, fácil de ler e o mais completa possível. O resto da documentação explica mais sobre como a documentação funciona para que você possa usar o melhor dela.
(Sim, isto é documentação sobre a documentação. Esteja certo de que nós não temos planos de escrever um documento sobre como ler a documentação sobre a documentação.)
Encontrar documentação¶
Django tem um monte de documentação – quase 450,000 e contando – então encontrar o que você precisa pode ser um pouco complicado. Alguns bons lugares para começar são em Página de Busca e Índice.
Ou você pode simplesmente navegar por ai!
Como a documentação é organizada¶
A documentação principal do Django é dividida em dois “pedaços” desenhada para diferentes necessidades:
O material introdutório é desenhado para pessoas novas ao Django – ou para desenvolvimento web em geral. Ela não cobre nada profundamente, mas dá uma visão abstraida de como é o “sentimento” de desenvolver em Django.
Os tópicos guias, em outra mão, se aprofundam em partes individuais do Django. Existem guias completos do sistema de modelos do Django, motor de template, formulários do framework, e muito mais.
Aqui é provavelmente onde você vai querer gastar a maior parte do seu tempo; se você seguir os guias, você vai aprender tudo que existe sobre Django.
Desenvolvimento web normalmente é amplo, não profundo – problemas aparecem em múltiplos domínios. Nós escrevemos um conjunto de guias how-to que respondem questões como “Como eu faço ....?”. Aqui você vai encontrar informação sobre gerando PDFs com Django, escrevendo tags de templates customizadas, e mais.
Respostas para questões usuais podem também ser encontradas no FAQ.
Os guias e how-to’s não cobrem cada uma das classes, funções e métodos disponíveis no Django – isto seria informação demais enquanto vocês está tentando aprender. Ao invés, detalhes sobre as classes individuais, funções, métodos e módulos são mantidos na referência. Aqui é onde você vai encontrar detalhes de uma função particular ou qualquer coisa que você precise.
Se você está interessado em fazer o deploy de um projeto para uso público, nossa doc tem diversos guias para várias diferentes configurações de deploy assim como a checklist de deploy para algumas coisas que você vai precisar pensar.
Finalmente, existe alguma documentação “especializada” não normalmente relevante para a maioria dos desenvolvedores. Isto inclui o notas da versão e documentação interna para aquele que querem adicionar código ao Django em si, e a algumas outras coisas que simplesmente não cabem em outros lugares.
Como a documentação é atualizada¶
Assim como a base de código do Django é desenvolvida e melhorada em base diária, a nossa documentação está melhorando consistentemente. Nós melhoramos a documentação por várias razões:
Para fazer correções do conteúdo, como correções gramaticais.
Para adicionar informação e/ou exemplo para seções existentes que precisam ser expandidas.
Para documentar funcionalidades que ainda não foram documentadas (a lista de tais funcionalidades está encolhendo, mas ainda existe).
Para adicionar documentação de novas funcionalidades, logo que estas são adicionadas, ou se o comportamento de uma API do Django mudar.
A documentação do Django é mantida no mesmo controle de versão que o seu código. Ela fica no diretório docs no nosso repositório. Cada documento online é separado em um arquivo de texto no repositório.
Onde obter isso¶
Você pode ler a documentação Django em várias formas. Eles estão, em ordem de preferência:
Na Web¶
A mais recente versão da documentação do Django fica em https://docs.djangoproject.com/en/dev/. Estas páginas HTML são geradas automaticamente com os arquivos no controle de versão. Isso significa que eles refletem o “último e o melhor” no Django – eles incluem cada última correção e adição, e eles explicam os últimos aspectos do Django, que podem estar disponíveis apenas na versão em desenvolvimento do Django. (Veja as “Diferenças entre versões” abaixo.)
Nós lhe encorajamos a ajudar a melhorar a doc enviando as modificações, correções e sugestões no sistema de tickets. Os desenvolvedores Django ativamente monitoram o sistema de Tickets e usam o seu feedback para melhorar a documentação todo mundo.
Note, entretanto, que os tickets devem ser explicitamente relacionados a documentação, ao invés de questões amplas de de suporte. Se você precisa de ajuda com uma configuração de Django particular, tente a lista de e-mails django-users ou o canal IRC #django ao invés.
Em texto plano¶
Para uma leitura offline, ou somente para sua conveniência, você pode ler a documentação Django em arquivo texto.
Se você está usando uma versão oficial do Django, note que no arquivo comprimido (tarball) do código é incluido o diretório docs/, que contem toda a documentação da versão.
Se você está usando a versão de desenvolvimento do Django (aka “trunk”), note que o diretório docs/ contem toda a documentação. Você pode atualizar seu git para pegar as últimas mudanças.
Um maneira não tecnológica de tomar vantagem sobre a documentação em texto é usando o utilitário grep Unix para buscar por frases em toda a documentação. Por exemplo, isto irá lhe mostrar cada menção da frase “max_length” em qualquer documento Django:
$ grep -r max_length /path/to/django/docs/
Como HTML, localmente¶
Você pode obter uma cópia local da documentação HTML seguindo estes passos fáceis:
A documentação do Django usa um sistema chamado Sphinx, para converter a partir de um texto simples para HTML você vai precisar instalar Sphinx por qualquer download e instalação do pacote através do site oficial do Sphinx, ou pelo
pip:$ pip install SphinxEntão, apenas use o
Makefileincluso para transformar a documentação em HTML:$ cd path/to/django/docs $ make html
Você precisará do GNU Make instalado para isso.
Se você estiver no Window, você pode, alternativamente, usar o arquivo batch:
cd path\to\django\docs make.bat htmlA documentação em HTML será colocado em
docs/_build/html.
Diferenças entre versões¶
Como já mencionado anteriormente, o texto da documentação em nosso repositório Git contém as “últimas e melhores” mudanças e adições. Estas mudanças geralmente incluem a documentação de novos aspectos adicionados na versão de desenvolvimento do Django – a versão Git (“trunk”) do Django. Por esta razão, é importante informar que a nossa política de manter documentação correta para varias versões do framework.
Nós seguimos esta política:
A documentação primária do djangoproject.com é uma versão HTML dos últimos docs no Git. Estes docs sempre correspondem com a última versão ofocial do Django, mais qualquer qualquer novo aspecto adicionado/modificado no framework desde o último lançamento.
A medida que adicionamos novos recursos a versão de desenvolvimento do Django, tentamos atualizar a documentação no mesmo commit do git
Para distinguir alterações/adições de recursos na documentação, nós usamos a frase: “Novo na versão X.Y”, sendo X.Y a próxima versão (assim sendo, o que está sendo desenvolvido).
Correções de documentação e melhorias podem ser versionadas de versões anteriores para a última revisão de seu branch, entretanyo, quando uma versão do Django não é mais suportada, a versão da documentação não receberá mais nenhuma atualização.
A página da web principal da documentação inclui links para documentação de todas as versões anteriores. Certifique-se de que você está usando a versão da documentação correspondente à versão do Django que você está usando!
