... e como contribuir.
A documentação do Django usa o sistema de documentação Sphinx, que por sua vez é baseado no docutils. A idéia básica é ter uma documentação leve em formato de texto-plano, que seja transformada em HTML, PDF, ou qualquer outro formato.
Na verdade para compilar a documentação localmente, você precisará instalar o Sphinx – easy_install Sphinx deve fazer a mágica.
Somente então, transforme tudo em html, para isso é só executar make html dentro do diretório docs.
Para começar a contribuir, você precisará ler a ReStructuredText Primer. Depois disso, você poderá ler sobre o Sphinx-specific markup que é utilizado para manipular os metadados, indexação, e cruzamento de referências.
A principal coisa que você deve manter em mente quando escrever ou editar a documentação é, quanto mais semântica você puder colocar, melhor. Então:
Adicione ``django.conrib.auth`` no seu ``INSTALLED_APPS``...
Não é tão útil quanto:
Adicione :mod:`django.contrib.auth` no seu :setting:`INSTALLED_APPS`...
Isto porque o Sphinx irá gerar links durante a compilação, que ajudarão muito os leitores. Basicamente não há limites para a quantidade de markup que você pode adicionar.
Além das markups built-in do Sphinx, a documentação do Django define algumas unidades de descrição extras:
Settings:
.. setting:: INSTALLED_APPS
Para linkar o setting, use :setting:`INSTALLED_APPS`.
Tags de template:
.. templatetag:: regroup
Para linkar, use :ttag:`regroup`.
Filtros de template:
.. templatefilter:: linebreaksbr
Para linkar, use :tfilter:`linebreaksbr`.
Lookups de campos (i.e. Foo.objects.filter(bar__exact=qualquercoisa)):
.. fieldlookup:: exact
Para linkar, use :lookup:`exact`.
Comandos do django-admin:
.. django-admin:: syncdb
Para linkar, use :djadmin:`syncdb`.
Opções de linha de comando do django-admin:
.. django-admin-option:: --traceback
Para linkar, use :djadminopt:`--traceback`.
Para um exemplo rápido de como tudo se agrupa, dá uma olhada nisso:
Primeiro, o documetno ref/settings.txt começa, dessa forma:
.. _ref-settings: Configurações disponíveis ========================= ...
Em seguida se olharmos para o documento topics/settings, você pode ver como um link para ``ref/settings funciona:
Configurações disponíveis ========================= Para uma lista completa das configurações disponíveis, veja :ref:`referencia do settings <ref-settings>`.
Depois, note como o settings (bem agora, no início) está anotado:
.. setting:: ADMIN_FOR ADMIN_FOR --------- Padrão: ``()`` (Tupla vazia) Usado para definir módulos do site de administraçaõ. este deve ser uma tupla de configurações de módulos (no formato ``'foo.bar.baz'``) para que este site tenha uma amdinistração. O site de administração usa isto em sua instrospecção automática da documentação de models, views e tags de template.
Isto marca o seguinte cabeçalho como um alvo "canonico" para a configuração ADMIN_FOR. Isto significa que toda vez que você fores mencionar ADMIN_FOR, podes referenciá-lo utilizando :setting:`ADMIN_FOR`.
Basicamente, é desta forma que tudo se encaixa.
O trabalho está na maioria feito, mas aqui tem o que falta, em ordem de prioridade.
Corrigir a documentação das generic views: adaptar o capítulo 9 do Django Book (considerar esse item de TODO minha permissão e licença) em topics/generic-views.txt; remover o material de introdução de ref/generic-views.txt e apenas deixar a referência de funções.
Mudar o "Added/changed na versão de desenvolvimento" chamar a diretiva adequada do Sphinx .. versionadded:: ou .. versionchanged::.
Checar links mal formados. Fazer isso rodando o make linkcheck e concertar todos os mais 300 errors/warnings.
Particularmente, olhar todos os links relativos; estes precisam ser modificados para as referências apropriadas.
A maior parte dos documentos index.txt têm textos de introdução muito curtos, ou quase inexistem. Cada um destes documentos precisar de de um bom conteúdo de introdução.
O glossário é muito superficial. Ele precisa ser preenchido.
E mais alvos de metadados: há vários lugares que se parecem com isso:
``File.close()`` ~~~~~~~~~~~~~~~~
... e deveria ser:
.. method:: File.close()
Que é, usar os metadados no lugar de títulos.
Adicionar mais links -- quase tudo o que um código inline literal, provavelmente pode ser transformado em um xref.
Veja o arquivo literals_to_xrefs.py no _ext -- este é um script shell para ajudar no trabalho.
Este será, ou provavelmente continuará sendo, um projeto sem fim.
Adicionar listas de informações de campos onde for apropriado.
Adicionar .. code-block:: <lang> para blocos literais para que eles sejam destacados.
Algumas dicas para fazer as coisas parecerem melhor:
Sempre que possível, use links. Então, use :setting:`ADMIN_FOR` ao invés de ``ADMIN_FOR``.
Algumas diretivas (.. setting::, por exemplo) são diretivas de estilo prefixado; elas vão antes da unidade que estão descrevendo. Estas são conhecidas como diretivas "crossref". Já outras (.. class::, ex.) geram suas próprias marcações; elas devem ir dentro da seção que estão descrevendo. São chamadas "unidades de descrição".
Você pode dizer quem é quem olhando no _ext/djangodocs.py; que registra as regras tanto para uma quanto para outra.
Quando estiver referindo-se a classes/funções/módulos, etc., você terá que usar um nome completo para o alvo (:class:`django.contrib.contenttypes.models.ContentType`).
Uma vez que isto não pareça ser uma saída incrível -- ela mostra o caminho completo para o objeto -- você pode prefixar o alto com um ~ para usar somente o final do caminho. Então :class:`~django.contrib.contenttypes.models.ContentType` mostrará somente um link com o título "ContentType".
Jul 29, 2009