# Documentação Django 5.2.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?

Well, we’ve always been big fans of learning by doing. At this point you should know enough to start a project of your own and start fooling around. As you need to learn new tricks, come back to the documentation. There’s also a bigger Django ecosystem out there for you to explore that the community has created.

We’ve put a lot of effort into making Django’s documentation useful, clear and as complete as possible. The rest of this document explains more about how the documentation works so that you can get the most out of it.

(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’s got a lot of documentation – almost 450,000 words and counting – so finding what you need can sometimes be tricky. A good place to start is the Índice. We also recommend using the builtin search feature.

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:

- The introductory material is designed for people new to Django – or to web development in general. It doesn’t cover anything in depth, but instead gives a high-level overview of how developing in Django “feels”.

- Os tópicos guias, por outro lado, se aprofundam em partes individuais do Django. Existem guias completos do sistema de modelos do Django, motor de template, framework de formulários, 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 personalizadas, 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.

- Finally, there’s some “specialized” documentation not usually relevant to most developers. This includes the release notes and internals documentation for those who want to add code to Django itself, and a few other things that don’t fit elsewhere.

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

Django’s documentation is kept in the same source control system as its code. It lives in the docs directory of our Git repository. Each document online is a separate text file in the repository.

## Onde obter isso

Você pode ler a documentação Django em várias formas. Eles estão, em ordem de preferência:

### On the web

A documentação da versão mais recente do Django fica em https://docs.djangoproject.com/en/dev/. Estas páginas HTML são geradas automaticamente vindas de arquivos textos do fonte. Isso significa que elas refletem a “ultima e maiores” do Django – elas incluem as úlimíssimas correções e adições, e elas discutem as últimas características do Django, a qual pode estar disponível para usuários da versão de desenvolvimento do Django. (Veja diferenças-entre-versões abaixp.)

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, however, that tickets should explicitly relate to the documentation, rather than asking broad tech-support questions. If you need help with your particular Django setup, try the Django Forum or the Django Discord server instead.

### Em texto plano

Para uma leitura offline, ou somente para sua conveniência, você pode ler a documentação Django em arquivo texto.

If you’re using an official release of Django, the zipped package (tarball) of the code includes a `docs/` directory, which contains all the documentation for that release.

If you’re using the development version of Django (aka the main branch), the `docs/` directory contains all of the documentation. You can update your Git checkout to get the latest changes.

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/

    ...\> grep -r max_length \path\to\django\docs\

### Como HTML, localmente

You can get a local copy of the HTML documentation following a few steps:

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

  / 

      $ python -m pip install Sphinx

      ...\> py -m pip install Sphinx

- Then, use the included `Makefile` to turn the documentation into 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

The text documentation in the main branch of the Git repository contains the “latest and greatest” changes and additions. These changes include documentation of new features targeted for Django’s next feature release. For that reason, it’s worth pointing out our policy to highlight recent changes and additions to Django.

Nós seguimos esta política:

- The development documentation at https://docs.djangoproject.com/en/dev/ is from the main branch. These docs correspond to the latest feature release, plus whatever features have been added/changed in the framework since then.

- Enquanto nós adicionamos funcionalidades à versão em desenvolvimento do Django, nós atualizamos a documentação na mesma transação do Git commit.

- To distinguish feature changes/additions in the docs, we use the phrase: “New in Django Development version” for the version of Django that hasn’t been released yet, or “New in version X.Y” for released versions.

- Documentation fixes and improvements may be backported to the last release branch, at the discretion of the merger, 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!