Dokumentacja#

Wskazówka

Dokumentacja na tej stronie jest napisana w ReStructuredText, w skrócie RST. Sprawdź Elementarz RST jeśli nie jesteś zaznajomiony/a z RST.

Ta strona nauczy cię jak pisać dobrą dokumentacje dla projektu UBports, którą będziesz mógł/a w przyszłości znaleźć na tej stronie.

Wytyczne dokumentacji#

Te zasady pokierują cie jak powinieneś/nnaś napisać twoją dokumentacje, aby uniknąć problemów ze stylem, formatowaniem lub linkowaniem.

Tytuł#

Wszystkie strony muszą zawierać tytuł, który będzie pokazany w spisie treści (lewy pasek) i na górze strony.

Tytuły powinny być „literowane jak zdanie”, zamiast „Literowane Jak Tytuł”. Na przykład:

Incorrect casing:
    Writing A Good Bug Report
Correct casing:
    Writing a good bug report
Correct casing when proper nouns are involved:
    Installing Ubuntu Touch on your phone

Nie ma jednej definicji, którą każdy powienen przestrzegać odnośnie wielkości liter w tytułe, za to wielkości liter w zdaniach są oczywiste. To pomaga zachować spójność kapitalizacji w spisie treści.

Tytuły stron są podkreślone znakami równości. Na przykład, znacznik dla Zgłaszanie błędów zawiera następujący tytuł:

Bug reporting
=============

Miej na uwadze, że:

Tytuł jest literowany jak zdanie
Tytuł jest podkreślony znakami równości
Podkreślenie obejmuje cały tytuł bez przechodzenia dalej

Niepoprawne tytuły zawierają:

Niepoprawne wielkości liter
Bug Reporting =============
Zbyt krótkie podkreślenie
Bug reporting =====
Zbyt długie podkreślenie
Bug reporting ================

Nagłówki#

Jest wiele poziomów nagłówków, które możesz zamieścić na stronie. Te poziomy są kolejno pokazane tutaj:

Page title
==========

Level one
---------

Level two
^^^^^^^^^

Level three
"""""""""""

Każdy poziom nagłówka tworzy sub-sekcje w globalnym drzewie spisu treści dostępnym, gdy dokumentacja jest budowana. W głównej (webowej) wersji tego dokumentu są pokazywane tylko cztery poziomy wielkości od głównego poziomu dokumentacji. Prosimy stronić od używania większym poziomów niż jest pokazane na tym drzewie, jako że utrudnia to nawigowanie po stronie. Jeśli musisz użyć tyle poziomów nagłówka, to znak, że twoja dokumentacja powinna być rozdzielona na więcej stron.

Spis treści#

Ludzie nie mogą nawigować się po twojej stronie jeśli jej nie znajdą. Także Sphinx nie może. Właśnie dlatego musisz dodać nowe strony do spisu treści.

Możesz to zrobić przez dodanie strony do pliku index.rst w tej samej lokalizacji, którą stworzyłeś/aś. Na przykład, jeśli stworzyłeś/aś plik nazywający się „newpage.rst”, chcesz dodać linie oznaczoną znakiem (>) w najbliższym indexie:

.. toctree::
    :maxdepth: 1
    :name: example-toc

    oldpage
    anotheroldpage
>   newpage

Kolejność ma znaczenie. Jeśli chciał/abyś, żeby twoja strona pojawiała się w konkretnym miejscu spisu treści umieść ją tam. W poprzednim przykładzie, nowa strona została by dodana na końcu spisu treści.

Przemieszczanie stron#

Czasem niezbędne staje się przemiesczenie strony z jednego miejsca dokumentacji na drugie. Ogółem mówiąc ma to na celu poprawienie czytelności dokumentu: Na przykład, więcej sensu ma dodanie strony zaraz po tej, którą dodałeś/aś w innej sekcji.

Jednakże, ludzie linkują do naszej dokumentacji z wielu źródeł i nie możemy tego kontrolować. Blogi, strony internetowe i inne strony dokumentacyjne mogą kierować ludzi tutaj używając linków, których mogą nigdy nie zaktualizować. Nie jest dobrym doświadczeniem otrzymać link z innej strony i wylądować na stronie 404, pozostawionym samym sobie by znaleźć się w zrestrukturyzowanej dokumentacji.

Dlatego używamy narzędzia nazywanego Rediraffe, aby uniknąć takich nieprzyjemności. Rediraffe tworzy stronę, która przekierowuje użytkownika ze starego, niepoprawnego linku do nowego, użytecznego linku. Proszę stwórz przekierowany link, kiedy zmieniasz nazwę strony albo przenosisz stronę do innej lokalizacji w dokumentacji. Linki przenoszące są tworzone poprzez wpisanie nazwy starego i nowego dokumentu relatywnie do katalogu głownego dokumentacji w pliku redirects.txt.

We use Rediraffe’s checkdiff builder to ensure that pages are not deleted from the documentation without a redirect in place. This builder is run as part of the build.sh script in the repository and as part of our automated build once you submit a Pull Request.

Poniżej są podano przykłady sytuacji, w których powinieneś/nnaś stwórzyć przekierowanie.

Przenosisz``systemdev/calendars.rst`` do appdev/calendars.rst. Dodaj je do pliku``redirects.txt``:

"systemdev/calendars.txt" "appdev/calendars.txt"

You are moving appdev/clickable.rst into several pages in appdev/clickable/ to give significantly more information about the tool than there was previously. You have created an introduction page, appdev/clickable/introduction.rst. In this case, it would be a good idea to redirect the old page to the new introduction page. This can be done by adding the following to redirects.txt:

"appdev/clickable.rst" "appdev/clickable/introduction.rst"

Ostrzeżenia#

Twoje edycje nie mogą wprowadzać żadnych ostrzeżeń do budowy dokumentacji. Jeśli wystąpią jakieś ostrzeżenia, kompilacja się nie powiedzie i twój pull request zostanie oznaczony czerwonym «X». Upewnij się, że twój RST jest prawidłowy i poprawny zanim swtorzysz pull request. Dzieje się to automatycznie (dzięki sphinx-build crashującemu z twoim błędem), jeśli podąrzałeś/aś zgodnie z poniższą instrukcją budowania.

Długość linijki#

Nie ma żadnych ograniczneń co do długości lini w tym repozytorium. Prosimy nie przerywać lini na bezwzględnej długości . Zamiast tego włącz zawijanie tekstu w twoim edytorze.

Workflow kontrybucji#

Następujące kroki pomogą ci wnieść kontrybucje do tej dokumentacji po tym jak napisałeś/aś dokument.

Informacja

Będziesz potrzebował/a konta Githuba, aby wykonać następne kroki. Jeśli nie go nie masz, kliknij <https://github.com/join>`_,aby zacząć proces tworzenia konta.

Forkowanie repozytorium#

Możesz dokonywać większych edycji naszej dokumentacji poprzez forkowanie ubports/docs.ubports.com na GitHubie. Jeśli nie jesteś pewien/na jak to zrobić zobacz fenomenalny poradnik GitHuba forking projects.

Budowanie dokumentacji#

Jeśli chciałbyś/ałabyś zbudować strone przed wysyłaniem PR’a (co powinnieneś/nnaś), podąrzaj za instrukcją na lokalnej kopii twojego forku repozytorium.

Dokumentacja może być zbudowana poprzez uruchomienie ./build.sh w głównym katalogu repozytorium. Skrypt stwórzy również wirtualne środowisku budowania w ~/ubportsdocsenv jeśli nie jest już stworzone.

Jeśli wszystko poszło dobrze, możesz wejść do lokalizacji _build/html i otworzyć index.html aby zobaczy dokumentacje UBports.

Jeśli masz problemy z budową dokumentacji zacznij od usunięcia środowiska budującego. Wpisz rm -r ~/ubportsdocsenv i spróbuj zbudować ponownie. Zależnie od tego kiedy pierwszy raz użyłeś/aś skryptu, możliwe jest, że będziesz musiał/a użyć komendy sudo.

Ostateczne sprawdzenie twojej kontrybucji#

Po tym jak stworzysz swój PR na githubie, system CI (continuous integration) wykona testową kompilacje twojej kontrybucji. Upewnij się dwa razy czy ta kompilacja zakończyła się sukcesem i czy wynik jest taki jaki oczekiwałeś/aś:

Przewiń na sam dół zakładki „Conversation” twojego PR’a na githubie, tutaj zobaczysz sprawdzenie (możliwe, że będziesz musiał/a kilknąć „Show all checks”)
Może ono mieć żółtą kropkę, tj. „pending” a więc poczekaj jeszcze chwile.
Albo może mieć czerwony X, tj. nie powiodło się. W tym przypadku prosze sprawdź dlaczego się nie powiodło
Jeśli pokazuje zielony znak to znaczy, że twój PR został pomyślnie zbudowany
Teraz klinij na „Details”,
potem „Artifacts” w prawym górnym rogu,
potem „_build/html/..index.html”,
i w końcu na „Go to start page”.

Teraz możesz przeglądać kompletną kompilacje strony dokumentacji UBports dodaną o twoją kontrybucje. Upewnij się, że twoje zmiany wyglądają ok.

Dostępne sposoby kontrybucji#

Tłumaczenia#

Dokumenty do tłumaczenia możesz znaleźć w ich projekcie na UBports Weblate.

Pisanie dokumentów nie w formacie RST#

Jeśli chciał/abyś napisać dokument dla UBports, ale nie czujesz się komfortowo z pisanie ReStructuredTex, prosze napisz w dowolnym formacie i umieść na Forum Ubports w odpowiedniej sekcji (prawdopodobnie General). Ktoś będzie w stanie poprawić twoją wersje roboczą i przepisać ją używając ReStructuredText.

Nie znam Gita#

If you’ve written a complete document in ReStructuredText but aren’t comfortable using Git or GitHub, please post it on the UBports Forum in the relevant section (likely General). Someone will be able to help you revise your draft and submit it to this documentation.

Obecnie do zrobienia (TODOs)#

Ta sekcja wypisuje rzeczy do zrobienia (TODOs), które zostały dołączone do tej dokumentacji. Jeśli wiesz jak naprawić jakieś z nich, prosze wyśli nam Pull Request, aby uczynić dokumentacje lepszą!

Aby stworzyć todo, dodaj taki znacznik do twojej strony:

.. todo::

   My todo text

Todo

There is also another way to create somewhat more featureful webapps, sometimes referred to as webapp+ or alternative container. This needst to be properly documented. It’s a simple qml app that can be easily configured. Creation is almost as simple as «classic» webapp, but result is more powerfull with the a nice navigation feature. A rather advanced example of this is the YouTube app from Mateo Salta which has quite some modifications on top of the template.

(oryginalny wpis znajduje się w pliku /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-pl/checkouts/latest/appdev/webapp/index.rst, w linii 19.)

Todo

Document the process for Nexus 4 (mako)

(oryginalny wpis znajduje się w pliku /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-pl/checkouts/latest/systemdev/kernel-hal.rst, w linii 57.)