Nós damos uma grande importância a consistência e legibilidade de nossa documentação. Afinal, Django foi criado em um ambiente jornalístico! Então nós tratamos a nossa documentação como nós tratamos o nosso código: nós tentamos melhorá-lo sempre que possível.
\nMudanças na documentação geralmente aparecem de duas formas:
\nMelhorias gerais: correção de ortografia, correções de erros e melhores explicações através de escrita clara e mais exemplos.
Novas funcionalidades: documentação de funcionalidades que foram adicionadas ao framework desde a última release.
Esta seção explica como os escritores podem construir suas mudanças na documentação de forma mais eficiente e menos suscetível a erros.
\nEmbora a documentação Django seja feita focando a leitura no formato HTML em https://docs.djangoproject.com/, nós editamos ela como uma coleção de arquivos de texto para maximizar a flexibilidade. Esses arquivos são armazenados no diretório docs/ da release Django.
Se você gostaria de contribuir com a nossa documentação, pegue a versão de desenvolvimento do Django do nosso repositório de código (veja Instalando a versão de desenvolvimento.). A versão de desenvolvimento possui a melhor e mais recente versão da documentação, assim como possui a melhor e mais recente versão do código. Nós também fazemos backport de correções e melhorias na documentação, dependendo da discrição do committer, para a branch da última release. Isto porque é extremamente vantajoso possuir a documentação para a última release correta e atualizada (see Diferenças entre versões).
\nA documentação do Django usa o sistema de documentação Sphinx, que por sua vez é baseado no docutils. A ideia básica é que uma documentação em texto plano com formatação simples é transformada em HTML, PDF, e muitos outros formatos.
\nPra efetivamente construir a documentação localmente, você provavelmente terá que instalar o Sphinx – pip install Sphinx deve ser o suficiente.
A partir desse momento, gerar o HTML é simples; basta executar o comando make html (ou make.bat html no Windows) de dentro do diretório docs.
To get started contributing, you’ll want to read the reStructuredText\nreference.
\nYour locally-built documentation will be themed differently than the\ndocumentation at docs.djangoproject.com.\nThis is OK! If your changes look good on your local machine, they’ll look good\non the website.
\nA documentação é organizada em vários categorias:
\nTutorials pega o leitor pelas mãos e o leva através de uma série de passos para criar algo.
\nO importante em um tutorial é ajudar o leitor a fazer algo útil, preferencialmente o mais rápido possível, para que ele passe a ganhar confiança.
\nExplique a natureza do problema que estamos tentando resolver, de modo que o leitor entenda o que nós estamos tentando alcançar. Não sinta que você precisa começar com explicações de como as coisas funcionam - o que importa é que o leitor fará, não o que você explica. Pode ser útil lembrar o que você já fez e explicar posteriormente.
\nTopic guides buscam explicar um conceito ou um assunto de modo bem abrangente.
\nFaça links para referências ao invés de repeti-las. Utilize exemplos e não seja relutante em explicar coisas que pareçam muito básicas para você - essa pode ser a explicação que outra pessoa precisa.
\nContextualizar ajuda os novatos a ligar o assunto a coisas que eles já sabem.
\nReference guides contém referências técnicas para as APIs. Eles descrevem o funcionamento do maquinário interno do Django e instruem em sua utilização.
\nMantenha o material de referência focado estritamente no assunto. Assuma que o leitor já entende os conceitos básicos envolvidos mas precisa saber ou ser lembrado de como o Django faz isso.
\nGuias de referência não são o local para explicações genéricas. Se você se encontrar explicando conceitos básicos, você deve querer mover o material para um guia em um assunto em específico.
\nHow-to guides são receitas que levam o leitor através de uma série de passos em assuntos chave.
\nO que importa mais em um guia how-to é o que um usuário deseja alcançar. Um how-to deve sempre estar orientado a resultados ao invés de focado em detalhes internos de como o Django implementa o que quer que esteja sendo discutido.
\nEsses guias são mais avançados que tutoriais e assumem algum conhecimento sobre como o Django trabalha. Assuma que o leitor seguiu os tutoriais e não hesite em enviar o leitor de volta para o tutorial apropriado ao invés de repetir o mesmo material.
\nQuando usar pronomes em referência a uma pessoa hipotética, tais como “um usuário com um cookie de sessão”, pronomes neutros (eles/seus/lhes) devem ser utilizados. Ao invés de:
\nele ou ela… utilize eles.
Dele ou dela… utilize deles.
Dele ou dela… utilize deles.
dele ou dela… use deles.
ele mesmo ou ela mesma… use eles mesmos.
Aqui vão algumas orientações de estilo para termos usados comumente por toda a documentação:
\nDjango – quando estiver se referindo ao framework, deve começar com letra maiúscula. Ele só deve ser escrito em letras minúsculas no código Python e no logo de djangoproject.com.
email – sem hífen.
MySQL, PostgreSQL, SQLite
SQL – quando estiver se referindo ao SQL, a pronunciação esperada deve ser “Ess Queue Ell” e não “sequel”. Portanto, em uma frase como “Retorna uma expressão SQL”, “SQL” deve ser precedido por “um” e não por “a”.
Python – quando estiver se referindo a linguagem, use letra maiúscula.
realize, customize, initialize, etc. – use o padrão Americano “ize” suffix, não “ise”
subclass – É uma única palavra sem o hífen, tanto para o verbo (“subclassear o modelo”) quanto para o substântivo (“criar uma subclasse”).
Web, World Wide Web, the Web – note que Web é sempre maiúsculo quando se referir a World Wide Web.
website – utilize uma palavra, tudo em minúsculas.
model – não tem maiúsculas.
template – não tem maiúsculas.
URLconf – utilize três as letras primeiras letras maiúsculas, sem espaço antes de “conf.”
view – não tem maiúsculas.
Estas regras regulam o formato de nossa documentação em reST (reStructuredText):
\nNa seção de títulos, só deixe em maiúsculas palavras iniciais e pronomes próprios.
Restrinja a documentação em até 80 caracteres de comprimento, a não ser que o código de exemplo seja significativamente mais difícil de ler quando quebrado em duas linhas, ou por outra boa razão.
A principal coisa a se manter em mente enquanto você escreve e edita documentos é que quanto mais marcação semântica você puder adicionar melhor. Então:
\nAdd ``django.contrib.auth`` to your ``INSTALLED_APPS``...\nNão é nem de perto melhor do que:
\nAdd :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...\nIsso porque o Sphinx irá gerar links apropriados para o mais recente, o que ajuda muito os leitores.
\nVocê pode prefixar o alvo com um ~ (isso é um til) para obter apenas a “última parte” do caminho. Então :mod:`~django.contrib.auth` só vai exibir um link com o titulo “auth”.
Utilize intersphinx para referenciar a documentação do Python e do Sphinx.
Adicione .. code-block:: <lang> para blocos literais tal que eles fiquem em destaque. Prefira ficar com o destaque simples usando os :: (dois-pontos duplos). Ele tem o benefício se caso o código conter um erro de sintaxe, ele não será destacado. Adicionando o .. code-block:: python, por exemplo, forçará o destaque da sentença mesmo que a sintaxe seja inválida.
Utilize esses estilos de cabeçalhos:
\n===\nOne\n===\n\nTwo\n===\n\nThree\n-----\n\nFour\n~~~~\n\nFive\n^^^^\nBesides Sphinx’s built-in markup, Django’s docs\ndefine some extra description units:
\nSettings:
\n.. setting:: INSTALLED_APPS\nPara redirecionar para uma configuração, utilize :setting:`INSTALLED_APPS`.
Tags de templates:
\n.. templatetag:: regroup\nPara redirecionar, utilize :ttag:`regroup`.
Filtros de templates:
\n.. templatefilter:: linebreaksbr\nPara redirecionar, utilize :tfilter:`linebreaksbr`.
Busca de campos (por exemplo, Foo.objects.filter(bar__exact=qualquercoisa)`):
\n.. fieldlookup:: exact\nPara redirecionar, utilize :lookup:`exact`.
Comandos do django-admin:
.. django-admin:: migrate\nPara redirecionar, utilize :djadmin:`migrate`.
Opções de linha de comando do django-admin:
.. django-admin-option:: --traceback\nPara redirecionar, utilize :option:`command_name --traceback` (ou omita command_name para as opções compartilhadas por todos os comandos como --verbosity).
Redirecionar para os tickets do Trac (tipicamente reservado a notas de releases de patches):
\n:ticket:`12345`\nNossa política para novas funcionalidades é:
\n\n\nToda a documentação de novas funcionalidades devem ser escritas de forma que fique claro que as funcionalidade só estão disponíveis na versão de desenvolvimento do Django. Assuma que os leitores da documentação estão usando a última release, e não a última versão de desenvolvimento.
\n
Nossa forma preferida de marcar novas funcionalidades é adicionando um prefixo na documentação de novas funcionalidades com “.. versionadded:: X.Y”, seguidas de uma linha em branco mandatória e uma descrição opcional (identada).
Melhorias gerais, ou outras mudanças para as APIs que deveriam ser enfatizadas devem usar a diretiva “.. versionchanged:: X.Y” (com o mesmo formato de versionadded mencionado acima.
Esses blocos versionadded e versionchanged devem ser “auto contidos”. Em outras palavras, já que nós só vamos manter essas anotações por volta de duas releases, é um bom poder remover a anotação e seus conteúdo sem ter que re-escoar, re-identar ou editar o texto ao redor. Por exemplo, ao invés de colocar a descrição inteira de uma mudança ou de uma nova funcionalidade em um block, faça algo como a seguir:
.. class:: Author(first_name, last_name, middle_name=None)\n\n A person who writes books.\n\n ``first_name`` is ...\n\n ...\n\n ``middle_name`` is ...\n\n .. versionchanged:: A.B\n\n The ``middle_name`` argument was added.\nColoque as considerações referentes as mudanças anotadas no final das seções, não no topo.
\nAlém disso, evite mencionar uma versão específica do Django fora dos blocos versionadded ou versionchanged. Mesmo dentro de um bloco, Ainda costuma ser redundantes fazer isso já que essas anotações irão renderizar como “Novo no Django A.B” e “Alterado no Django A.B”, respectivamente.
Se a função, atributo, etc. é adicionado, também pode ser usado uma anotação versionadded como a seguir:
.. attribute:: Author.middle_name\n\n .. versionadded:: A.B\n\n An author's middle name.\nNós podemos simplesmente remover a anotação .. versionadded:: A.B sem quaisquer mudanças de identação quando a hora chegar.
Otimize a compressão das imagens quando possível. Para arquivos PNG, utilize OptiPNG e o “advpng” da AdvanceCOMP:
\n$ cd docs/\n$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`\n$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`\nIsso é baseado na versão 0.7.5 do OptiPNG. Versões mais antigas podem reclamar da opção --strip all dizendo que existirá perda de qualidade.
Para um rápido exemplo de como tudo se encaixa, considere este exemplo hipotético:
\nPrimeiro, o documento ref/settings.txt pode ter um leiaute geral como esse:
========\nSettings\n========\n\n...\n\n.. _available-settings:\n\nAvailable settings\n==================\n\n...\n\n.. _deprecated-settings:\n\nDeprecated settings\n===================\n\n...\nDepois, o documento topics/settings.txt pode ser algo assim:
You can access a :ref:`listing of all available settings\n<available-settings>`. For a list of deprecated settings see\n:ref:`deprecated-settings`.\n\nYou can find both in the :doc:`settings reference document\n</ref/settings>`.\nNós usamos o elmento de referência cruzada do Sphinx doc quando nós queremos redirecionar para outro documento como um todo e o elemento ref quando queremos redirecionar para uma localização arbitrária dentro do documento.
Depois, repare em como os settings são anotados:
\n.. setting:: ADMINS\n\nADMINS\n======\n\nDefault: ``[]`` (Empty list)\n\nA list of all the people who get code error notifications. When\n``DEBUG=False`` and a view raises an exception, Django will email these people\nwith the full exception information. Each member of the list should be a tuple\nof (Full name, email address). Example::\n\n [('John', 'john@example.com'), ('Mary', 'mary@example.com')]\n\nNote that Django will email *all* of these people whenever an error happens.\nSee :doc:`/howto/error-reporting` for more information.\nIsso marca o próximo cabeçalho como o alvo “canônico” para o setting ADMINS. Isto significa que sempre que eu falar sobre ADMINS, eu posso redirecionar para ele usando :setting:`ADMINS`.
Isso é basicamente como tudo se encaixa.
\nAntes de fazer o commit das suas documentações, é uma boa ideia rodar o verificador ortográfico. Você terá que instalar alguns pacotes primeiro:
\nDepois de instalá-los e de dentro do diretório docs, rode o comando make spelling. Palavras erradas (se existirem) além do arquivo e o número da linha onde eles ocorream serão salvos em _build/spelling/output.txt.
Se você encontrar falso-positivos (erros que na verdade estão corretos), faça uma das coisas a seguir:
\nColoque em volta o código ou nomes de marcas/tecnologias acentos graves (`).
Encontre um sinônimo que o verificador ortográfico reconheça.
Se, e somente se, você tiver certeza que a palavra que você está usando está correta - adicione ela em docs/spelling_wordlist (por favor mantenha a lista em ordem alfabética).
Veja Localizing the Django documentation Se você quer ajudar a traduzir a documentação para outras linguagens.
\ndjango-adminLink para este cabeçalho#O Sphinx pode gerar uma página de manual para o comando django-admin. Isso é configurado em docs/conf.py. Diferentemente de outras documentações geradas, essa página man deve ser incluída no repositório do Django e de suas releases em docs/man/django-admin.1. Não existe a necessidade de atualizar esse arquivo quando estiver atualizando a documentação, já que ele é atualizado durante o processo de release.
Para gerar uma versão atualizada da página man, roda o comando make man dentro do diretório docs. A nova página man será escrita em docs/_build/man/django-admin.1.