Como Criar documentação no Playground Swift

Como Criar documentação no Playground Swift

Quando abri o mais recente blog da Apple “Padrões Playground” post do blog , fiquei impressionado com a sua aparência.

Ao invés de criarem a documentação dos vários blocos com os habituais comentários, eles conseguiram colocar notas vistosas com as explicações de cada exemplo de código. É como se trata-se de um livro interativo. Aqui está um exemplo deste tipo de documentação:

Exemplo Patterns playground 

E claro, a minha primeira interrogação foi: “Como é que eles fazem isso ?! Posso fazer também? Eu quero fazer isso!”. Depois de alguma bisbilhotice, acho que descobri como fazer isso.

Eu já sou um crente no uso de Playgrounds do XCode na aprendizagem da linguagem. Eu acho que usando esta técnica de documentação haverá um potencial maior na experiência do Playgroundainda mais na criação de material didático e de uma forma mais profissional.

Fazendo um simples exemplo (The File -> New Playground ) e converter os comentários para o novo estilo de documentação.

 

Antes:

MyPlayground com documentacao playground antes

 

Depois:MyPlayground com documentacao playground depois

 

Explorando Mais.

  1. Crie um playground (e lembre-se onde o salva).
  2. Navegue até ao arquivo .playground que salvou.
  3. Clique com o botão direito no arquivo .playground, e escolha “Mostrar Conteúdo do Pacote”.
  4. Adicionar uma nova pasta chamada “Documentation”.
  5. Crie um novo documento HTML na pasta Documentation. O documento deve conter a marcação HTML e a explicação de texto que você gostaria de melhorar no seu playgroundCertifique-se de que o documento HTML está bem formado. Vou descrever um exemplo no final para que perceba mais facilmente.
  6. Embora opcional, eu recomendo denominar seu arquivo HTML com um CSS apropriado. Adicionando um arquivo CSS e referência a ele dentro do arquivo HTML que você criou é provavelmente uma boa ideia (tudo isso é permitido na documentação do Playground).
  7. Abra o contents.xcplayground com um editor de texto à sua escolha, clicando com o botão direito e escolha “Abrir com”.
  8. Modifique o XML para que o <sections> contenha um nó <documenttion>, como mostrado nas linhas de código em destaque no exemplo abaixo.:
  9. Salve e abra o Playground no XCode 6. O seu Playground agora deve conter esta documentação!

    Como forma de melhorar a minha própria documentação do Playground, eu simplesmente copiei um dos arquivos HTML e CSS a partir do arquivo da Apple Patterns Playground. De seguida modifiquei  o codigo para conter o material educacional que eu queria no meu playground, personalizei os estilos para o que eu pretendia, acrescentei o nó <documentation> no arquivo contents.xcplayground, salvei, e voila documentação bem mais Vistosa!

 

Fonte: andrewcbancroft.com

Comments