Projeto copiloto de desempenho

Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.

Resumo do projeto

Organização de código aberto:
Copiloto de performance
Redator técnico:
arzoo14
Nome do projeto:
Converta o conteúdo de áreas de projeto de livros para o formato readthedocs e reStructuredText com a nova meta de melhoria dos diagramas.
Duração do projeto:
Duração padrão (3 meses)

Project description

RESUMO:

Um site da comunidade desempenha um papel essencial em uma organização de código aberto porque espalha a ideia de ofertas que a comunidade fornece, suas contribuições preciosas, suas habilidades, documentações, tutoriais etc. Portanto, meu projeto terá como objetivo aumentar a usabilidade e a facilidade para todos os colaboradores de código aberto, transferindo e atualizando o conteúdo das áreas do projeto de livros, ou seja, o conteúdo do livro, a documentação da API REST e o conteúdo estruturado da comunidade para o formato moderno de marcação do site para o formato moderno. Este projeto também beneficiará os colaboradores da comunidade, permitindo que eles alterem e estendam esse conteúdo com mais facilidade. Além disso, como uma meta extravagante, os diagramas na documentação serão aprimorados para dar uma aparência mais profissional.

PROPOSTA:

  1. VISÃO GERAL: no momento, a documentação do copiloto de desempenho existe em diversos formatos. Isso inclui livros em PCP no formato de docbook, a API REST em formato de página de manual e guias de pbench em formato de markdown. O grupo de mantenedores atual da organização identificou que precisa de uma solução que não precisa de manutenção e que permita que a comunidade de desenvolvedores se concentre totalmente em manter o conteúdo de maneira simplificada e fácil. Portanto, de acordo com as necessidades atuais da organização, vou implementar os seguintes objetivos durante esta temporada de Documentos Google:

    1. Converter o conteúdo do documento para o formato reStructuredText e hospedá-lo no site readthedocs.
    2. conversão da documentação da API REST em um formato adequado para desenvolvedores, ou seja, no formato reStructuredText e hospedagem no site readthedocs.
    3. Converter o conteúdo em pbench Markdown para o formato reStructuredText e hospedá-lo no site readthedocs.
    4. As metas adicionais seriam melhorar os diagramas presentes na documentação.

  2. IMPLEMENTAÇÃO: atualmente, a documentação do copiloto de desempenho não está presente em um formato específico. Sempre que o conteúdo da documentação precisar ser alterado, ele deverá ser alterado por um conjunto restrito de usuários. Os membros ativos da comunidade não conseguem mudar e ampliar o conteúdo da documentação.

Vou deixar a organização superar essas limitações durante este GSoD com a ajuda do formato reStructuredText, Read the Docs (RTD) e Sphinx.

O Read the Docs (RTD) simplifica a documentação do software, automatizando a criação, o controle de versões e a hospedagem de 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, do Mercurial ou do 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 app Documentos Google e vincular a conta do GitHub. Depois, vamos selecionar o repositório do GitHub para o qual vamos criar a documentação e então a mágica acontece.

Leia os documentos: - Clonar nosso repositório. - Criar versões HTML, PDF e ePub da nossa documentação na nossa agência principal. - Indexar nossa documentação para permitir a pesquisa de texto completo. - Criar objetos Version de cada tag e ramificação em nosso repositório, o que nos permite hospedá-los opcionalmente. - Ativar um webhook no nosso repositório. Assim, quando enviarmos código para qualquer ramificação, nossa documentação será recriada.

O Sphinx é um gerador de documentação confiável que oferece vários 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 usando as mesmas fontes. - Podemos usar reStructuredText para escrever documentação. - Um sistema extenso de código de referência cruzada e documentação. - Exemplos de código em destaque de sintaxe. - Um ecossistema dinâmico de extensões próprias e de terceiros.

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

2.1. Conversão para o formato reStructuredText: A primeira etapa será converter o conteúdo da documentação para o formato reStructuredText. Cada capítulo terá um arquivo rst separado, que terá apenas o conteúdo desse capítulo. Por exemplo, o manual do usuário e do administrador de co-piloto de desempenho inclui oito capítulos. Isso significa que haverá oito arquivos rst diferentes correspondentes a esses oito capítulos. O nome do primeiro arquivo será igual ao nome do capítulo para evitar confusão no futuro. Uma lista de figuras, tabelas e listas de exemplos está lá em três arquivos iniciais diferentes. O primeiro conteúdo será inserido em hiperlinks da mesma forma que está atualmente. O mesmo vai ser usado para a documentação da API REST e o conteúdo do pbench. Todos os itens necessários, como negrito, itálico, sublinhado, marcadores, tabelas, tamanho da fonte, estilo de código, tamanho da imagem, alinhamento etc., serão resolvidos ao converter o conteúdo para o formato de novo.

2.2. Integração do rst com o Sphinx:

O ReadtheDocs usa o Sphinx e o reStructuredText (rst) como padrões. Como o Sphinx é pré-instalado no meu sistema, começarei criando um diretório dentro do projeto (chamado de documentação de copiloto de desempenho) para armazenar os documentos: $ cd /path/to/project $ mkdir docs

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

Este início rápido ajudará a criar a configuração necessária. Na maioria dos casos, podemos aceitar apenas os padrões, mas, quando necessário, podemos fazer as alterações essenciais no arquivo de configuração. Quando terminar, teremos um index.rst, um conf.py e alguns outros arquivos. Em index.rst, adicionarei todos os detalhes necessários sobre o copiloto de desempenho e criarei títulos para os livros, a documentação da API REST e os guias de pbench. Ao clicar em um título, todos os materiais de documentação serão abertos.

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

O index.rst será integrado ao index.html no diretório de saída da nossa documentação (normalmente _build/html/index.html). Assim que tivermos a documentação do Sphinx em um repositório público, poderemos começar a usar o recurso "Ler os documentos" importando nossos documentos.

Quando adicionarmos qualquer arquivo .rst em nossa documentação, que corresponda a esse arquivo, três outros arquivos serão gerados, um na pasta doctrees com a extensão .doctree, o segundo na pasta HTML com 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, conectarei a conta do Read The Docs ao GitHub e importarei o projeto de documentação para criação. 2. Criação da documentação: alguns segundos após a conclusão do processo de importação, o código será buscado automaticamente em nosso repositório público e a documentação será criada.

  2. WEBHOOKS: O principal método usado pelo Ler os Documentos 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 a cada confirmação, mesclagem ou outra alteração no repositório, o recurso "Ler os documentos" é notificado. Quando recebemos uma notificação de webhook, determinamos se a mudança está relacionada a uma versão ativa do projeto e, se estiver, um build é acionado para essa versão.

Dessa forma, qualquer pessoa (administradores, mentores, colaboradores da comunidade) pode alterar, estender ou manter a documentação da comunidade, e nenhum conjunto restrito específico de usuários será necessário para definir o que deve ser adicionado à documentação ou o que deve ser removido da documentação.

  1. TEMAS: temas, layouts, designs e outras funcionalidades de HTML, como pesquisa, serão de acordo com as necessidades e diretrizes da comunidade. Nesse período de formação, vou discutir tudo isso com os membros da comunidade.
  1. ESTIMAR OBJETIVO: Como uma meta extra, vou melhorar os diagramas presentes na documentação. Atualmente, os diagramas são principalmente desenhos simples em preto e branco. Vou usar mais cores, sombreamento, dimensionamento, consistência e uma aparência mais clara ou profissional nas imagens.

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

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

COMPROVANTE DE CONCEITO

Converta uma pequena parte do livro do PCP (formato de livro de documentos) para o primeiro formato e o hospedei no site readthedocs. Encontre-o 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 do código para que as alterações feitas no repositório de código sejam refletidas no site.

CRONOGRAMA E EXIBIÇÕES

PERÍODO DE VINCULAÇÃO DA 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 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 todos os três tópicos ou três sites diferentes correspondentes aos três tópicos serão discutidos durante o período de vínculo com a comunidade.

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

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

***De 21 a 27 de setembro de 2020 [SEMANA 2] Conversão do conteúdo do documento no primeiro formato para os próximos quatro capítulos do guia "Guia para 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 para o primeiro formato de todos os quatro capítulos do Guia do programador.

***De 5 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 do manual para o formato rst. A página de destino principal será vinculada 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 primeiro formato. O índice de série temporal escalonável 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 a 25 de outubro de 2020 [SEMANA 6] Conversão do índice de serviços de host de PMAPI para o formato rst. O índice dos serviços de hospedagem 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 1o de novembro de 2020 [SEMANA 7] - Se faltar algo nas últimas semanas, ele será abordado primeiro. - Hospedagem da documentação da API REST no site readthedocs. - Blogs (do meu projeto GSoD) nas últimas duas semanas e na semana atual.

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

***De 9 a 15 de novembro de 2020 [SEMANA 9] - Continuidade da conversão do conteúdo de markdown no primeiro formato para os guias de pbench. - Hospedagem dos guias do pbench no site readthedocs. - Blog (do meu projeto GSoD) na semana passada e na semana atual.

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

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

PERÍODO DE FINALIZAÇÃO DO PROJETO [30 de novembro a 5 de dezembro de 2020 ]

  • Inatividade do lápis. Trabalhar no envio final e garantir que está tudo bem.
  • Envio dos relatórios do projeto, também conhecidos como produtos de trabalho finais.
  • Envio das avaliações do sucesso dos projetos e da experiência de trabalho com os mentores.