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

Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.

Podsumowanie projektu

Organizacja open source:
Wspólny program pilotażowy
Pisarz techniczny:
arzoo14
Nazwa projektu:
Przekształć treść obszarów projektu książki na format readthedocs i reStructuredText, a przy tym dążyć do dalszego ulepszania wykresów.
Długość projektu:
Standardowa długość (3 miesiące)

Opis projektu

Streszczenie:

Witryna społecznościowa odgrywa kluczową rolę w organizacji open source, ponieważ propaguje ofertę społeczności, jej cenny wkład, umiejętności, dokumentację, samouczki itp. Mój projekt będzie miał na celu zwiększenie przydatności i łatwości obsługi dla wszystkich użytkowników oprogramowania open source przez przenoszenie i aktualizowanie treści z obszarów projektu książki, czyli na przykład treści z obszarów projektu książki, treści w formacie docbook. O dokumentację w formacie REST można mówić w postaci nowoczesnej dokumentacji interfejsu API. Dzięki temu projektowi osoby ze społeczności będą mogły łatwiej wprowadzać zmiany i rozszerzać te treści. Ponadto ulepszymy diagramy w dokumentacji, aby nadać im bardziej profesjonalny wygląd.

OFERTA:

  1. PRZEGLĄD: Dokumentacja wspólnego programu pilotażowego dotyczącego skuteczności jest obecnie dostępna w kilku różnych formatach. Są to książki PCP w formacie docbook, interfejs API REST w formacie manpage i przewodniki Pbench w formacie Markdown. Obecna grupa opiekunów w organizacji zauważyła, że potrzebuje rozwiązania, które będzie jak najmniej bezobsługowe, a które pozwoli społeczności programistów całkowicie skupić się na utrzymaniu treści w prosty i prosty sposób. W związku z aktualnymi potrzebami organizacji w tym sezonie korzystania z Dokumentów Google wdrożę następujące cele:

    1. Konwersja treści z dokumentu do formatu reStructuredText i przechowywanie jej w witrynie readthedocs.
    2. Konwersja dokumentacji interfejsu API REST z instrukcji na format przyjazny dla programistów, tj. na format reStructuredText i przechowywanie w witrynie readthedocs.
    3. Konwersja treści w formacie MarkDown na plik reStructuredText i przechowywanie jej w witrynie readthedocs.
    4. Cele rozciągnięte polegają na ulepszeniu diagramów występujących w dokumentacji.

  2. WDROŻENIE: Obecnie dokumentacja wspólnego wdrożenia pilotażowego dotyczących skuteczności nie jest dostępna w określonym formacie. Gdy zajdzie potrzeba zmiany treści dokumentacji, musi ona zostać zmieniona przez ograniczoną grupę użytkowników. Aktywni członkowie społeczności nie tak łatwo mogą zmieniać i rozszerzać treść dokumentacji.

Pozwolę organizacji przezwyciężyć te ograniczenia podczas GSoD przy pomocy formatów reStructuredText, Read the Docs (RTD) i Sfinx.

Zapoznaj się z Dokumentami (RTD), aby uprościć dokumentację oprogramowania dzięki automatyzacji tworzenia, obsługi wersji i przechowywania dokumentów. Jest to platforma hostingowa dla dokumentacji wygenerowanej przez Sphinxa. Wykorzystuje moc Sphinxa i dodaje kontrolę wersji, wyszukiwanie pełnotekstowe i inne przydatne funkcje. Pobieraje on pliki kodu i dokumentów z Git, Mercurial lub Subversion, a następnie buduje i hostuje naszą dokumentację. W naszym projekcie wykorzystamy GitHuba, ponieważ 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 wybierzemy repozytorium GitHub, dla którego chcemy utworzyć dokumentację.

Po przeczytaniu dokumentów: – Sklonuj nasze repozytorium. – Utwórz wersje HTML, PDF i ePub naszej dokumentacji z gałęzi głównej. - Zapoznaj się z naszą dokumentacją, aby umożliwić wyszukiwanie pełnotekstowe. – Tworzenie obiektów wersji z każdego tagu i gałęzi w naszym repozytorium, co pozwoli nam je hostować również opcjonalnie. – Aktywuj webhooka w naszym repozytorium, aby po przekazaniu kodu do dowolnej gałęzi przebudowana była dokumentacja.

Sphinx to wiarygodny generator dokumentacji oferujący wiele przydatnych funkcji do tworzenia dokumentacji technicznej, w tym: – Generowanie stron internetowych, drukowanych plików PDF, dokumentów na czytniki e-booków (ePub) oraz wiele innych, a wszystko to z tych samych źródeł. – Do tworzenia dokumentacji możemy użyć obiektu reStructuredText. – Rozbudowany system porównywania kodu i dokumentacji. – Przykładowy kod z wyróżnioną składnią. – tętniący życiem ekosystem rozszerzeń własnych i innych firm.

Zacznę od przekonwertowania 2 książek PCP, które są dostępne w formacie docbook, na format pierwszy, po konwersji dokumentacji API REST z formatu man page na format pierwszego rodzaju, a następnie konwersji treści pliku Pbench Markdown na format pierwszego poziomu i na koniec hostując wszystkie te materiały w witrynie Readthedocs. Cele rozszerzone polegają na poprawieniu diagramów w dokumentacji.

2.1. Konwersja na format reStructuredText: Pierwszym krokiem będzie przekonwertowanie treści dokumentacji na format reStructuredText. Każdy rozdział będzie mieć osobny plik pierwszy, który będzie zawierał tylko jego treść. Na przykład Przewodnik użytkownika i Przewodnik dla administratora dotyczący wspólnego wdrożenia pilotażowego w zakresie wydajności składa się z 8 rozdziałów. Oznacza to, że tych 8 rozdziałów będzie odpowiadać 8 różnym plikom. Nazwa pierwszego pliku będzie taka sama jak tytuł rozdziału, aby uniknąć nieporozumień w przyszłości. Lista ilustracji, tabel i przykładów będzie znajdować się w 3 różnych pierwszych plikach. Pierwsza treść zostanie utworzona w taki sam sposób, w jaki obecnie znajduje się hiperlink. To samo zostanie użyte w dokumentacji interfejsu API REST i zawartości pliku pbench. Podczas konwertowania treści na pierwszy format zostaną uwzględnione wszystkie niezbędne elementy, takie jak pogrubienie, kursywa, podkreślenie, listy punktowane, tabele, rozmiar czcionki, styl kodu, rozmiar obrazu czy wyrównanie.

2.2. Integracja pierwszych z usługami Sphinx:

Aplikacja ReadtheDokumentacja korzysta z elementów Sphinx i reStructuredText (wcześniej). Ponieważ oprogramowanie Sphinx zostało już zainstalowane w moim systemie, zacznę od utworzenia w projekcie katalogu (noszącego nazwę Dokumentacja wspólnego programu pilotażowego dotyczącego wydajności), w którym będą przechowywane dokumenty: $ cd /path/to/project $ mkdir docs

Następnie uruchom polecenie „Sfinx-quickstart”: $ cd docs $ sphinx-quickstart

Ten krótki przewodnik pomoże Ci utworzyć niezbędną konfigurację. W większości przypadków możemy zaakceptować wartości domyślne (ale w razie potrzeby możemy wprowadzić niezbędne zmiany w pliku konfiguracji). Po zakończeniu znajduje się plik index.rst, conf.py i kilka innych plików. W indeksie index.rst dodam wszystkie niezbędne szczegóły dotyczące wspólnego wdrożenia pilotażowego dotyczącego wydajności oraz utworzę nagłówki książek, dokumentacji interfejsu API REST i przewodników po pbench. Kliknięcie przez użytkownika dowolnego nagłówka spowoduje otwarcie wszystkich materiałów z danymi pod tym nagłówkiem.

UWAGA: projekt strony indeksu będzie zgodny z zgodą przełożonych i członków społeczności. Będzie się on zmieniał w zależności od potrzeb i wymagań.

Plik index.rst zostanie wbudowany w element index.html w naszej dokumentacji wyjściowej (zwykle jest to _build/html/index.html). Gdy dokumentacja Sphinx pojawi się w publicznym repozytorium, możemy zacząć korzystać z funkcji Przeczytaj dokumenty, importując nasze dokumenty.

Gdy dodamy do naszej dokumentacji dowolny plik .rst odpowiadający temu plikowi, zostaną wygenerowane trzy inne pliki – jeden w folderze doctrees z rozszerzeniem .doctree, drugi w folderze HTML z rozszerzeniem .html i trzeci w folderze html/_sources z rozszerzeniem .rst.txt.

  1. HOSTING DOKUMENTACJI: Przechowywanie dokumentacji w internecie składa się z 2 etapów: 1. Importowanie dokumentacji: w pierwszym kroku połączę konto Read The Docs z GitHubem i zaimportuję nasz projekt dokumentacji w celu kompilacji. 2. Tworzenie dokumentacji: w ciągu kilku sekund po zakończeniu procesu importowania kod zostanie automatycznie pobrany z naszego publicznego repozytorium, a dokumentacja zostanie utworzona.

  2. WEBHOOKS: główną metodą odczyty w Dokumentach jest wykrywanie zmian w dokumentacji i wersjach przy użyciu webhooków. Webhooki są konfigurowane u naszego dostawcy repozytorium, takiego jak GitHub, a po każdym zatwierdzeniu, scalaniu i innej zmianie w naszym repozytorium otrzymujesz powiadomienie „Read the Docs”. Gdy otrzymujemy powiadomienie webhook, określamy, czy zmiana jest powiązana z aktywną wersją projektu i czy jest, a jeśli tak, to wyzwalana jest dla niej kompilacja.

W ten sposób każdy (administrator, mentorzy, współtwórcy społeczności) może zmieniać, rozszerzać i utrzymywać dokumentację społeczności. Nie jest konieczna konkretna grupa użytkowników z ograniczeniami, która dba o to, co należy dodać do dokumentacji lub co z niej usunąć.

  1. MOTYWY: Motywy, układy, projekty i inne funkcje HTML, takie jak wyszukiwanie, będą dostosowane do potrzeb i wytycznych społeczności. W okresie więzi ze społecznością omówię wszystkie te kwestie z członkami społeczności.
  1. CEL ROZCIĄGNIĘCIE: W ramach ambitnego celu ulepszę diagramy w dokumentacji. Obecnie diagramy są w większości proste czarno-białe rysunki. Wprowadzę więcej kolorów, cieniowania, skalowania i spójności oraz nadaję zdjęciom ładniejszy / bardziej profesjonalny wygląd.

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

W ramach modelu koncepcyjnego ulepszyliśmy jeden z diagramów w dokumentacji za pomocą Draw.io. Znajdziesz go tutaj: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

DOKUMENT POCZĄTKOWY

Niewielka część książki PCP (w formacie docbook) została przekonwertowana na pierwszy format i udostępniona w witrynie readthedocs. Znajdziesz go tutaj.

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

Mam też skonfigurowane w repozytorium kodu webhooki, dzięki czemu zmiany wprowadzone w repozytorium kodu będą odzwierciedlane w witrynie.

HARMONOGRAM I MATERIAŁY DOSTAWY

OKRES BĘDĄCY SPOŁECZNOŚCI: [17 sierpnia – 13 września 2020 r.]

Spędzam ten czas, aby zapoznać się ze społecznością, przejrzeć dokumentację i omówić wiele kwestii z mentorami, aby uniknąć złych decyzji na wczesnym etapie całego procesu. W tym czasie będę omawiać tematy, układy, projekty oraz inne funkcje, takie jak wyszukiwanie, pasek nawigacyjny itp., z mentorami i członkami społeczności. Decyzja dotycząca nazwy projektu i tego, czy powstanie jedna witryna, w której będą hostowane wszystkie 3 zagadnienia, czy też 3 różne strony powiązane z każdym z nich, zostanie omówiona w okresie zacieśniania więzi ze społecznością.

KROK OPRACOWANIA DOKUMENTÓW [14 września – 30 listopada 2020 r.]

***Od 14 września 2020 r. do 20 września 2020 r. [TYDZIEŃ 1] Konwersja zawartości audiobooka na pierwszy format 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] Konwersja zawartości książki na pierwszy format na potrzeby pierwszych 4 rozdziałów Przewodnika dla użytkowników i administratorów.

***Od 28 września do 4 października 2020 r. [TYDZIEŃ 3] Konwersja treści książki na pierwszy format wszystkich 4 rozdziałów Przewodnika dla programistów.

***Od 5 do 11 października 2020 r. [TYDZIEŃ 4] – Hostowanie obu książek PCP w witrynie Readthedocs. – Przekształcenie dokumentacji interfejsu API typu REST ze strony man na format pierwszego formatu. W tym czasie będzie uwzględniana główna strona docelowa. - Blogowanie (w ramach mojego projektu GSoD) przez ostatnie trzy tygodnie i bieżący tydzień.

***Od 12 do 18 października 2020 r. [TYDZIEŃ 5] Konwersja indeksu skalowalnego ciągu czasowego na pierwszy format. Indeks skalowalnego ciągu czasowego obejmuje: 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 do 25 października 2020 r. [TYDZIEŃ 6] Konwersja indeksu usług hosta PMAPI na pierwszy format. 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 ciągu ostatnich tygodni zostało coś jeszcze, zostanie to opłacone w pierwszej kolejności. – Dokumentacja interfejsu API REST w witrynie readthedocs. - Blogowanie (w ramach mojego projektu GSoD) przez ostatnie dwa tygodnie i bieżący tydzień.

***Od 2 do 8 listopada 2020 r. [TYDZIEŃ 8] Konwersja treści w formacie Markdown na pierwszy format na potrzeby przewodników pbench.

***Od 9 do 15 listopada 2020 r. [TYDZIEŃ 9] – Kontynuacja konwersji treści Markdown na pierwszy format na potrzeby przewodników pbench. – Umieszczenie przewodników po pbench w witrynie readthedocs. - Blogowanie (z mojego projektu GSoD) w ostatnim tygodniu i bieżącym tygodniu.

***Od 16 do 22 listopada 2020 r. [TYDZIEŃ 10] – Implementacja funkcji wyszukiwania na stronie indeksu do wyszukiwania dowolnych treści w witrynach po jej nazwie. – Rozpoczęcie realizacji celów rozszerzonych.

***Od 23 do 30 listopada 2020 r. [TYDZIEŃ 11] – Poprawa wszystkich diagramów zawartych w dokumentacji. - Ostatni blog (z mojego projektu GSoD) z ostatniego i bieżącego tygodnia. – Sprawdzanie, czy baza kodu jest zgodna ze standardami kodowania. Jeśli nie, zmień je na standardowe.

OKRES FINALIZACJI PROJEKTU [30 listopada – 5 grudnia 2020 r.]

  • Przerwa w korzystaniu z ołówka. Pracujemy nad ostatecznym zgłoszeniem i upewniam się, że wszystko jest w porządku.
  • Przesyłanie raportów dotyczących projektu, nazywane też końcowymi usługami roboczymi.
  • Przesłanie oceny powodzenia projektów i doświadczeń z mentorami.