# documentação Django 2.0.8

# 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 Sphinx

- Então, apenas use o `Makefile` incluso 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 html

- A 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).
- Documentation fixes and improvements may be backported to the last release branch, at the discretion of the committer, however, once a version of Django is no longer supported, that version of the docs won’t get any further updates.
- 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!