Projeto copiloto de desempenho

Esta página contém os detalhes de um projeto de escrita técnica aceito para o Temporada dos Documentos Google.

Resumo do projeto

Organização de código aberto:
Copiloto de performance
Redator técnico:
arzoo14
Nome do projeto:
Converter o conteúdo das áreas de projeto do livro para o formato readthedocs e reStructuredText, além da meta de melhoria de diagramas.
Duração do projeto:
Duração padrão (três meses)

Project description

RESUMO:

Um site da comunidade desempenha um papel essencial em uma organização de código aberto porque ele divulga a ideia das ofertas que a comunidade oferece, as contribuições valiosas, as habilidades, a documentação, os tutoriais etc. Portanto, meu projeto visa aumentar a usabilidade e a facilidade para todos os colaboradores de código aberto transferindo e atualizando o conteúdo das áreas do projeto do livro, ou seja, o conteúdo do docbook, a documentação da API REST e o conteúdo do pbench markdown para o formato reStructuredText, de modo que ele possa ser hospedado no site moderno da comunidade readthedocs.io. Esse projeto também vai beneficiar os colaboradores da comunidade, permitindo que eles mudem e ampliem esse conteúdo com mais facilidade. Além disso, como meta estendida, os diagramas na documentação serão aprimorados para dar uma aparência mais profissional.

PROPOSTA:

  1. VISÃO GERAL: Atualmente, a documentação do Performance Co-Pilot está disponível em vários formatos. Eles incluem livros de PCP no formato de docbook, API REST no formato de página de manual e guias de pbench no formato Markdown. Assim, o grupo de manutenção atual da organização identificou que precisa de uma solução que seja o mais livre de manutenção possível e que permita que a comunidade de desenvolvedores se concentre totalmente na manutenção do conteúdo de uma maneira simplificada e fácil. De acordo com as necessidades atuais da organização, vou implementar os seguintes objetivos durante esta temporada de documentos do Google:

    1. Converter o conteúdo do docbook para o formato reStructuredText e hospedar no site do readthedocs.
    2. Converter a documentação da API REST de página de manual para um formato amigável para desenvolvedores, ou seja, o formato reStructuredText, e hospedar no site do readthedocs.
    3. Converter o conteúdo do pbench MarkDown para o formato reStructuredText e hospedá-lo no site readthedocs.
    4. As metas de alongamento seriam melhorar os diagramas presentes na documentação.

  2. IMPLEMENTAÇÃO: No momento, a documentação do Performance Co-Pilot não está em um formato específico. Sempre que o conteúdo da documentação precisar ser alterado, isso precisa ser feito por um conjunto restrito de usuários. Não é tão fácil para os membros ativos da comunidade mudar e ampliar o conteúdo da documentação.

Vou permitir que a organização supere essas limitações durante este GSoD com a ajuda do formato reStructuredText, Ler os documentos (RTD) e Sphinx.

O Read the Docs (RTD) simplifica a documentação de software automatizando a criação, a versão e a hospedagem dos nossos documentos. É uma plataforma de hospedagem para documentação gerada pelo Sphinx. Ele usa o poder do Sphinx e adiciona controle de versões, pesquisa de texto completo e outros recursos úteis. Ele extrai arquivos de código e documentos do Git, Mercurial ou Subversion e, em seguida, cria e hospeda nossa documentação. Vamos usar o GitHub no nosso projeto, porque ele é o sistema mais usado para acessar códigos.

Para começar, vamos criar uma conta do Read the Docs e vincular a conta do GitHub. Em seguida, selecionaremos o repositório do GitHub para o qual queremos criar a documentação. Nesse momento, a mágica acontece.

O Read the Docs vai: - Clonar nosso repositório. - Crie versões HTML, PDF e ePub da nossa documentação usando a ramificação principal. - Indexar nossa documentação para permitir pesquisa de texto completo. - Criar objetos Version de cada tag e ramificação em nosso repositório, o que nos permitirá hospedá-los também opcionalmente. - Ative um webhook no repositório para que, quando enviarmos o código para qualquer ramificação, a documentação seja recriada.

O Sphinx é um gerador de documentação autoritativo com muitos recursos excelentes para escrever documentação técnica, incluindo: - Gerar páginas da Web, PDFs para impressão, documentos para e-readers (ePub) e muito mais, tudo das mesmas fontes. - Podemos usar o reStructuredText para escrever a documentação. - Um sistema extenso de código de referência cruzada e documentação. - Exemplos de código com sintaxe destacada. - Um ecossistema vibrante de extensões próprias e de terceiros.

Começarei convertendo os dois livros do PCP que estão presentes em formato de docbook para o formato rst, seguindo a conversão da documentação da API REST do formato de página do manual para o formato rst, em seguida, a conversão do conteúdo de markdown pbench para o formato rst e, no final, hospedando tudo isso no site readthedocs. As metas de alongamento seriam melhorar os diagramas na documentação.

2.1. Conversão para o formato reStructuredText: a primeira etapa é converter o conteúdo da documentação para o formato reStructuredText. Cada capítulo terá um arquivo rst separado, que conterá apenas o conteúdo daquele capítulo. Por exemplo, o livro "Performance Co-Pilot User's and Administrator's Guide" inclui oito capítulos. Isso significa que haverá oito arquivos rst diferentes correspondentes a esses oito capítulos. O nome do arquivo rst será o mesmo do capítulo para evitar confusões no futuro. Uma lista de figuras, tabelas e listas de exemplos vai estar em três arquivos rst diferentes. O primeiro conteúdo terá o hiperlink completo da mesma forma que está presente atualmente. O mesmo será usado para a documentação da API REST e o conteúdo do pbench. Todas as coisas necessárias, como negrito, itálico, sublinhado, marcadores de tópicos, tabelas, tamanho da fonte, estilo de código, tamanho da imagem, alinhamento etc., serão cuidadas durante a conversão do conteúdo para o formato rst.

2.2. Integração da primeira com o Sphinx:

O ReadtheDocs usa o Sphinx e o reStructuredText (rst) como padrões. Como o Sphinx está pré-instalado no meu sistema, vou começar criando um diretório dentro do projeto (chamado de Performance Co-Pilot Documentation) para armazenar os documentos: $ cd /path/to/project $ mkdir docs

Depois disso, execute o sphinx-quickstart aqui: $ cd docs $ sphinx-quickstart

Este guia de início rápido vai mostrar como criar a configuração necessária. Na maioria dos casos, basta aceitar os padrões, mas, quando necessário, é possível fazer as mudanças essenciais no arquivo de configuração. Quando terminar, teremos um index.rst, um conf.py e alguns outros arquivos. Em index.rst, vou adicionar todos os detalhes necessários sobre o Copiloto de performance e criar títulos para os livros, a documentação da API REST e os guias de pbench. Quando o usuário clica em um dos títulos, todos os materiais de documentação abaixo dele são abertos.

OBSERVAÇÃO: o design da página de índice será de acordo com o consentimento dos mentores e dos membros da comunidade e será alterado de acordo com as necessidades e os requisitos.

O index.rst será criado no index.html no diretório de saída da documentação (normalmente _build/html/index.html). Depois de ter a documentação do Sphinx em um repositório público, podemos começar a usar o Read the Docs importando nossos documentos.

Quando adicionarmos um arquivo .rst à nossa documentação, três outros arquivos serão gerados correspondentes a esse arquivo: um na pasta "doctrees" com a extensão .doctree, outro na pasta "HTML" com a extensão .html e o terceiro na pasta html/_sources com a extensão .rst.txt.

  1. HOSPEDAGEM DA DOCUMENTAÇÃO: A hospedagem de documentação na Internet consiste em duas etapas: 1. Importação da documentação: como primeira etapa, vou conectar a conta do Read The Docs ao GitHub e importar nosso projeto de documentação para criar. 2. Criação da documentação: alguns segundos após a conclusão do processo de importação, o código será buscado automaticamente do nosso repositório público, e a documentação será criada.

  2. WEBHOOKS: O principal método usado pelo Read the Docs para detectar alterações na documentação e nas versões é o uso de webhooks. Os webhooks são configurados com nosso provedor de repositório, como o GitHub, e o Read the Docs é notificado a cada confirmação, mesclagem ou outra mudança no repositório. Quando recebemos uma notificação de webhook, determinamos se a mudança está relacionada a uma versão ativa do nosso projeto. Se estiver, um build é acionado para essa versão.

Assim, qualquer pessoa (administradores, mentores e colaboradores da comunidade) pode mudar, ampliar ou manter a documentação da comunidade, e não é necessário que um conjunto específico de usuários cuide do que deve ser adicionado ou removido da documentação.

  1. TEMAS: temas, layouts, designs e outras funcionalidades de HTML, como a pesquisa, serão de acordo com as necessidades e diretrizes da comunidade. Durante esse período, vou discutir tudo isso com os membros da comunidade.
  1. META ADICIONAL: Como meta adicional, vou melhorar os diagramas presentes na documentação. Atualmente, os diagramas são desenhos simples em preto e branco. Vou apresentar mais cores, sombreamento, dimensionamento, consistência e uma aparência geralmente mais organizada / profissional nas imagens.

Para isso, vou usar odraw.io (ou qualquer outra ferramenta com o consentimento do mentor).

Como prova de conceito, melhorei um dos diagramas presentes na documentação com a ajuda do draw.io. Confira aqui: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

PROVA DE CONCEITO

Eu converti uma pequena parte do livro do PCP (formato de docbook) para o formato rst e o hospedei no site do readthedocs. Confira aqui.

Site: https://pcp-books.readthedocs.io/en/latest/ Código: https://github.com/arzoo14/PCP_Books_Demo

Também configurei webhooks no repositório de código para que as mudanças feitas no repositório de código sejam refletidas no site.

CRONOGRAMA E RESULTADOS

PERÍODO DE VINCULAMENTO COM A COMUNIDADE [17 de agosto a 13 de setembro de 2020 ]

Vou passar esse tempo me familiarizando com a comunidade, analisando a documentação e discutindo muitas coisas com os mentores para garantir que nenhuma decisão ruim seja tomada no início do processo. Durante esse período, vou discutir os temas, layouts, designs e outras funcionalidades, como pesquisa, barra de navegação etc., com os mentores e os membros da comunidade. A decisão sobre o nome do projeto e se haverá um único site para hospedar os três temas ou três sites diferentes correspondentes aos três temas será discutida durante o período de integração da comunidade.

PERÍODO DE DESENVOLVIMENTO DO DOCUMENTO [14 de setembro a 30 de novembro de 2020 ]

***De 14 de setembro de 2020 a 20 de setembro de 2020 [SEMANA 1] Conversão do conteúdo do documento no formato inicial para os quatro primeiros capítulos do Guia de usuários e administradores.

***De 21 de setembro de 2020 a 27 de setembro de 2020 [SEMANA 2] Conversão do conteúdo do documento no formato inicial para os próximos quatro capítulos do Guia de usuários e administradores.

***De 28 de setembro de 2020 a 4 de outubro de 2020 [SEMANA 3] Conversão do conteúdo do documento no formato inicial para os quatro capítulos do Guia do Programador.

***De 5 de outubro de 2020 a 11 de outubro de 2020 [SEMANA 4] — Hospedagem dos dois livros do PCP no site readthedocs. - Conversão da documentação da API REST da página de manual para o formato rst. A página de destino principal será coberta durante esse período. - Blogs (do meu projeto GSoD) nas últimas três semanas e na semana atual.

***De 12 a 18 de outubro de 2020 [SEMANA 5] Conversão do índice de série temporal escalonável para o formato rst. O índice de séries temporais escalonáveis abrange o seguinte: GET /series/query , GET /series/values, GET /series/descs , GET /series/labels, GET /series/metrics , GET /series/sources , GET /series/instances , GET /series/load

***De 19 de outubro de 2020 a 25 de outubro de 2020 [SEMANA 6] Conversão do índice de serviços de host da PMAPI para o formato rst. O índice de serviços do host da PMAPI abrange o seguinte: GET /pmapi/context, GET /pmapi/metric, GET /pmapi/fetch , GET /pmapi/children GET /pmapi/indom, GET /pmapi/profile , GET /pmapi/store , GET /pmapi/derive GET /pmapi/metrics

***De 26 de outubro de 2020 a 1º de novembro de 2020 [SEMANA 7] - Se houver algum conteúdo das últimas semanas, ele será abordado primeiro. - Hospedagem da documentação da API REST no site do readthedocs. - Blogar (meu projeto GSoD) nas últimas duas semanas e na semana atual.

***De 2 de novembro de 2020 a 8 de novembro de 2020 [SEMANA 8] Conversão do conteúdo de marcação para o formato primeiro para os guias de pbench.

***De 9 a 15 de novembro de 2020 [SEMANA 9] - Continuamos com a conversão do conteúdo Markdown para formato rst nos guias de pbench. - Hospedagem dos guias de pbench no site do readthedocs. - Blogs (do meu projeto GSoD) na última semana e na atual.

***De 16 a 22 de novembro de 2020 [SEMANA 10] - Implementação da funcionalidade de pesquisa na página de índice para pesquisar qualquer conteúdo pelo nome nos sites. - Início das metas ambiciosas.

***De 23 a 30 de novembro de 2020 [SEMANA 11] - Melhoria de todos os diagramas presentes na documentação. - O blog final (do meu projeto GSoD) da última semana e da atual. - Verificar se a base de código segue os padrões de codificação. Caso contrário, mude para os padrões.

PROJECT FINALIZATION PERIOD [ November 30 - December 5, 2020 ]

  • Tempo de inatividade do lápis. Estou trabalhando no envio final e verificando se está tudo certo.
  • Envio dos relatórios do projeto, também conhecidos como produtos finais do trabalho.
  • Envio das avaliações do sucesso dos projetos e da experiência de trabalho com os mentores.