Wspólny projekt pilotażowy dotyczący wydajności

Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.

Podsumowanie projektu

Organizacja open source:
Współpracownik skuteczności
Pisarz techniczny:
arzoo14
Nazwa projektu:
Przekształcanie treści obszarów projektu książki na format readthedocs i reStructuredText wraz z celem dodatkowym polegającym na ulepszaniu diagramów.
Długość projektu:
Standardowa długość (3 miesiące)

Opis projektu

STRESZCZENIE:

Strona internetowa społeczności odgrywa kluczową rolę w organizacji open source, ponieważ rozpowszechnia idee oferowane przez społeczność, jej cenne wkłady, umiejętności, dokumentację, samouczki itp. Mój projekt ma na celu zwiększenie użyteczności i łatwości obsługi dla wszystkich autorów open source poprzez przeniesienie i zaktualizowanie treści obszarów projektu książki, czyli treści docbooka, dokumentacji interfejsu REST API i treści markdown pbench do formatu reStructuredText, aby można je było hostować na nowoczesnej stronie readthedocs.io dla społeczności. Ten projekt przyniesie też korzyści osobom, które przyczyniają się do rozwoju społeczności, ponieważ ułatwi im ona zmianę i rozszerzenie tych treści. Dodatkowo, jako ambitniejsze zadanie, diagramy w dokumentacji zostaną ulepszone, aby wyglądały bardziej profesjonalnie.

PROPOSAL:

  1. PRZEGLĄD: dokumentacja Performance Co-Pilot jest obecnie dostępna w kilku formatach. Są to między innymi książki PCP w formacie docbook, interfejs API REST w formacie manpage i przewodniki Pbench w formacie Markdown. Obecna grupa utrzymania w organizacji stwierdziła więc, że potrzebuje rozwiązania, które nie wymaga obsługi, a społeczność programistów będzie mogła całkowicie skupić się na utrzymaniu treści w sposób wydajny i prosty. Zgodnie z obecnymi potrzebami organizacji w tym sezonie Dokumentów Google będę realizować te cele:

    1. Konwertowanie zawartości docbooka do formatu reStructuredText i hostowanie jej w witrynie readthedocs.
    2. Konwertowanie dokumentacji interfejsu API REST z manpage na format przyjazny dla programistów, np. reStructuredText, i hostowanie jej na stronie readthedocs.
    3. Konwersja zawartości MarkDown na format reStructuredText i hosting jej w witrynie readthedocs.
    4. Celem rozciągającym będzie ulepszenie diagramów przedstawionych w dokumentacji.

  2. WDROŻENIE: dokumentacja wspólnego programu pilotażowego dotyczącego wydajności nie jest obecnie dostępna w określonym formacie. Gdy wymagana jest zmiana zawartości dokumentacji, musi to być ograniczona grupa użytkowników. Aktywni członkowie społeczności nie mogą łatwo zmieniać i rozszerzać treści dokumentacji.

Pozwolę organizacji przezwyciężyć te ograniczenia podczas tego szkolenia GSoD dzięki formatom reStructuredText, RTD i Sphinx.

Przeczytaj dokument Dokumenty (RTD), który upraszcza dokumentację oprogramowania dzięki automatyzacji tworzenia, obsługi wersji i hostowania naszych dokumentów. Jest to platforma hostingowa do dokumentacji wygenerowanej przez Sphinxa. Wykorzystuje on możliwości Sphinxa i dodaje kontrolę wersji, wyszukiwanie pełnego tekstu oraz inne przydatne funkcje. Pobiera on pliki kodu i dokumentów z Git, Mercurial lub Subversion, a potem kompiluje i hostuje naszą dokumentację. W naszym projekcie użyjemy GitHuba, ponieważ jest to najczęściej używany system do uzyskiwania dostępu do kodu.

Na początek utworzymy konto Read the Docs i połączymy je z kontem GitHub. Następnie wybieramy repozytorium GitHub, dla którego chcemy utworzyć dokumentację i tam zaczyna się magia.

Read the Docs: - skopiuj nasze repozytorium. – Utwórz wersje HTML, PDF i EPUB dokumentacji z gałęzi głównej. – Indeksowanie naszej dokumentacji w celu umożliwienia wyszukiwania pełnego tekstu. – Tworzenie obiektów wersji z każdego tagu i gałęzi w naszym repozytorium, co pozwala nam opcjonalnie hostować te wersje. – Aktywuj webhook w naszym repozytorium, aby po wypchnięciu kodu do dowolnej gałęzi została odtworzona nasza dokumentacja.

Sphinx to wiarygodny generator dokumentacji, który udostępnia wiele przydatnych funkcji do pisania dokumentacji technicznej, w tym: – umożliwia tworzenie stron internetowych, plików PDF do druku i dokumentów na czytniki e-booków (ePub) z tych samych źródeł. - Możemy użyć elementu reStructuredText do pisania dokumentacji. – obszerny system wzajemnych odniesień w kodzie i dokumentacji; – Przykłady kodu zaznaczone w składni. – dynamiczny ekosystem rozszerzeń własnych i firm zewnętrznych.

Zaczniemy od przekonwertowania dwóch książek PCP z formatu docbook na rst, a potem przekształcimy dokumentację interfejsu API REST z formatu strony man na rst. Następnie przekształcimy zawartość pbench w formacie markdown na rst, a na końcu opublikujemy wszystkie te treści na stronie readthedocs. Cele dodatkowe to ulepszanie diagramów w dokumentacji.

2.1. Konwersja na format reStructuredText: Pierwszym krokiem będzie konwersja treści dokumentacji na format reStructuredText. Każdy rozdział będzie miał oddzielny pierwszy plik, który będzie zawierał tylko treść tego rozdziału. Na przykład przewodnik dla użytkownika i administratora Performance Co-Pilot zawiera 8 rozdziałów. Oznacza to, że będzie 8 różnych plików rst odpowiadających 8 rozdziałom. Aby uniknąć nieporozumień w przyszłości, nazwa pierwszego pliku będzie taka sama jak tytuł rozdziału. Lista rysunków, tabel i list przykładów będzie dostępna w 3 różnych plikach rst. Pierwsza treść zostanie w pełni podlinkowana w taki sam sposób, w jaki obecnie występuje. To samo dotyczy dokumentacji interfejsu API REST i treści pbench. Podczas konwertowania treści na format rst zostaną uwzględnione wszystkie niezbędne elementy, takie jak pogrubienie, kursywa, podkreślenie, punkty wyliczenia, tabele, rozmiar czcionki, styl kodu, rozmiar obrazu, wyrównanie itp.

2.2. Integracja pierwszego ze Sfinksem:

ReadtheDocs używa domyślnie Sphinxa i reStructuredText (rst). Ponieważ Sphinx jest wstępnie zainstalowany w moim systemie, zacznę od utworzenia katalogu w ramach projektu (o nazwie Performance Co-Pilot Documentation), który będzie zawierać dokumenty: $ cd /path/to/project $ mkdir docs

Następnie uruchom sphinx-quickstart w: $ cd docs $ sphinx-quickstart

Ten krótki przewodnik przeprowadzi Cię przez proces tworzenia niezbędnej konfiguracji. W większości przypadków możesz po prostu zaakceptować wartości domyślne (ale w razie potrzeby możesz wprowadzić niezbędne zmiany w pliku konfiguracji). Po zakończeniu tego procesu tworzymy pliki index.rst, conf.py i inne. Do pliku index.rst dodam wszystkie niezbędne informacje o Performance Co-Pilot i utworzę nagłówki zarówno dla książek, dokumentacji interfejsu REST API, jak i przewodników pbench. Gdy użytkownik kliknie dowolny z tych nagłówków, otworzy wszystkie materiały z dokumentacji pod tym nagłówkiem.

UWAGA: projekt strony indeksu będzie zgodny z zaakceptowanym przez mentorów i członków społeczności i będzie zmieniany zgodnie z ich potrzebami i wymaganiami.

Plik index.rst zostanie wbudowany w plik index.html w katalogu wyjściowym naszej dokumentacji (zwykle jest to _build/html/index.html). Gdy mamy już dokumentację Sphinx w publicznym repozytorium, możemy zacząć korzystać z funkcji Czytaj dokumenty, importując nasze dokumenty.

Gdy dodamy do naszej dokumentacji dowolny plik .rst, zostanie wygenerowany odpowiedni plik .doctree, drugi plik .html oraz trzeci plik .rst.txt w folderze html/_sources.

  1. HOSTOWANIE DOKUMENTACJI: Hostowanie dokumentacji w internecie składa się z 2 etapów: 1. Importowanie dokumentacji: najpierw połączę konto Read The Docs z GitHubem i zaimportuję projekt dokumentacji do kompilacji. 2. Tworzenie dokumentacji: w kilka sekund po zakończeniu procesu importowania kod zostanie automatycznie pobrany z naszego publicznego repozytorium, a dokumentacja zostanie utworzona.

  2. WEBHOOKS: Podstawową metodą używaną w Reader Dokumentów do wykrywania zmian w dokumentacji i wersjach są webhooki. Webhooki są konfigurowane u dostawcy repozytorium, takiego jak GitHub, i po każdym zatwierdzeniu, połączeniu lub innej zmianie w naszym repozytorium Read the Docs jest powiadamiany. Gdy otrzymamy powiadomienie webhooka, sprawdzamy, czy zmiana jest związana z aktywna wersją naszego projektu. Jeśli tak, uruchamiamy kompilację tej wersji.

Dzięki temu każdy (administratorzy, mentorzy, autorzy w społeczności) może zmieniać, rozszerzać lub aktualizować dokumentację społeczności. Nie trzeba będzie też tworzyć specjalnego zestawu użytkowników z ograniczonym dostępem, którzy będą odpowiadać za to, co należy dodać do dokumentacji lub usunąć z niej.

  1. TEMAT: motywy, układy, projekty i inne funkcje HTML, takie jak wyszukiwarka, będą dostosowane do potrzeb i wytycznych społeczności. W okresie budowania społeczności omówię wszystkie te kwestie z członkami społeczności.
  1. AMBICJYJNY CEL: Jako ambitniejszy cel, poprawię diagramy w dokumentacji. Obecnie diagramy to głównie proste czarno-białe rysunki. Wprowadzę więcej kolorów, cieniowania, skalowania, spójności i ogółem bardziej schludny / profesjonalny wygląd obrazów.

W tym celu będę korzystać z drewnia.io (lub innego narzędzia za zgodą mentora).

W ramach Proof of Concept ulepszyłem jeden z diagramów w dokumentacji za pomocą draw.io. Znajdziesz go tutaj: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

DOKUMENT POMYSŁU

Przekształciliśmy niewielką część książki PCP (w formacie docbook) do formatu rst i opublikowaliśmy ją na stronie readthedocs. Znajdziesz go tutaj.

Strona internetowa – https://pcp-books.readthedocs.io/en/latest/ Kod – https://github.com/arzoo14/PCP_Books_Demo

Skonfigurowałem też webhooki w repozytorium kodu, dzięki czemu zmiany wprowadzone w repozytorium kodu zostaną odzwierciedlone w witrynie.

HARMONOGRAM I WYNIKI

OKRES ZWIĄZANIA ZE SPOŁECZNOŚCIĄ [17 sierpnia – 13 września 2020 r.]

W tym czasie zapoznam się z tą społecznością, przejrzę dokumentację i porozmawiam z mentorami, aby mieć pewność, że na wczesnym etapie procesu nie podejmiemy złych decyzji. W tym czasie będę omawiać z mentorami i członkami społeczności motywy, układy, projekty i inne funkcje, takie jak wyszukiwarka czy pasek nawigacyjny. W trakcie okresu budowania społeczności zostanie podjęta decyzja o nazwie projektu oraz o tym, czy będzie to jedna strona internetowa zawierająca wszystkie 3 tematy, czy 3 różne strony internetowe odpowiadające 3 temom.

OKRES TWORZENIA DOKUMENTU [14 września – 30 listopada 2020 r.]

***14–20 września 2020 r. [TYDZIEŃ 1] Przekształcanie zawartości podręcznika na format rst w przypadku pierwszych 4 rozdziałów przewodnika dla użytkowników i administratorów.

***Od 21 września 2020 r. do 27 września 2020 r. [TYDZIEŃ 2] Przekształcanie zawartości podręcznika w formacie docbook na format rst w przypadku kolejnych 4 rozdziałów przewodnika dla użytkowników i administratorów.

***Od 28 września do 4 października 2020 r. [TYDZIEŃ 3] Przekształcanie zawartości dokumentu w formacie rst w przypadku wszystkich 4 rozdziałów książki Przewodnik dla programisty.

***Od 5 października 2020 r. do 11 października 2020 r. [TYDZIEŃ 4] - Hosting obu książek PCP na stronie readthedocs. – konwersja dokumentacji interfejsu API REST z formatu strony man na format rst. W tym czasie będzie to główna strona docelowa. – prowadzenie bloga (w ramach projektu GSoD) przez ostatnie 3 tygodnie i obecny tydzień.

***Od 12 października do 18 października 2020 r. [TYDZIEŃ 5] Konwersja indeksu Scalable Time Series na format rst. Indeks skalowalnych ciągów czasowych obejmuje te operacje:GET /series/query , GET /series/values, GET /series/descs , GET /series/labels,GET /series/metrics , GET /series/sources , GET /series/instances , GET /series/load

***Od 19 października 2020 r. do 25 października 2020 r. [WEEK 6] Konwersja indeksu usług hosta PMAPI na format pierwszy. Indeks usług hosta PMAPI obejmuje: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

***Od 26 października 2020 r. do 1 listopada 2020 r. [TYDZIEŃ 7] - Jeśli w ostatnich tygodniach pozostało coś do zrobienia, zostanie to zrobione w pierwszej kolejności. - Udostępnienie dokumentacji interfejsu API typu REST w witrynie readthedocs. – prowadzenie bloga (w ramach projektu GSoD) przez ostatnie 2 tygodnie i obecny tydzień.

***Od 2 do 8 listopada 2020 r. [TYDZIEŃ 8] Przekształcanie treści w formacie markdown w format rst w przypadku przewodników pbench.

***Od 9 listopada 2020 r. do 15 listopada 2020 r. [TYDZIEŃ 9] – Kontynuowano konwertowanie treści Markdown na format pierwszego z nich na potrzeby przewodników Pbench. – hosting przewodników pbench na stronie readthedocs. - Blogi (w ramach projektu GSoD) z ostatniego i bieżącego tygodnia.

***Od 16 listopada do 22 listopada 2020 r. [TYDZIEŃ 10] – Wdrożenie funkcji wyszukiwania na stronie indeksu umożliwiającej wyszukiwanie dowolnych treści w witrynie po ich nazwie. – Rozpoczęcie stosowania celów długofalowych.

***Od 23 listopada do 30 listopada 2020 r. [TYDZIEŃ 11] - Ulepszenie wszystkich diagramów w dokumentacji. – Ostatni wpis na blogu (z projektu GSoD) z ostatniego i bieżącego tygodnia. – Sprawdzanie, czy kod źródłowy jest zgodny ze standardami kodowania. Jeśli nie, zmień je zgodnie ze standardami.

OKRES KOŃCOWEGO PRZETWIERZANIA PROJEKTU [30 listopada–5 grudnia 2020 r.]

  • Przerwa w działaniu ołówka. Pracujemy nad ostateczną wersją zgłoszenia i upewniamy się, że wszystko jest w porządku.
  • przesłanie raportów projektu, czyli końcowych produktów pracy;
  • Przesłanie oceny sukcesu projektów i doświadczeń z współpracy z mentorami.