Pisanje dokumentacije

Kada dodajete dodatke ili doprinosite novim značajkama za Qt Creator, vjerojatno želite da drugi ljudi o njima saznaju i da ih mogu koristiti. Stoga biste trebali priložiti i njihovu dokumentaciju. Slijedite smjernice u ovom odjeljku kako biste osigurali da se vaša dokumentacija dobro uklapa u ostatak dokumentacije za Qt Creator.

Kada doprinosite dodatkom, trebali biste napisati dokumentaciju i za programere koji koriste Qt Creator i za one koji ga razvijaju.

Dodajte sljedeće vrste tema u priručnik za Qt Creator ili kao zaseban priručnik za dodatak ako se vaš dodatak nalazi u vlastitom spremištu:

• Opći pregled, koji opisuje svrhu vašeg dodatka iz perspektive korisnika Qt Creator.
• Tutorijali, koji opisuju kako izraditi različite vrste Qt aplikacija.
• Teme "kako napraviti", koje opisuju kako izvršiti zadatke pomoću vašeg dodatka kao dijela Qt Creator a.
• Referentne teme koje sadrže informacije koje programeri povremeno trebaju potražiti.

Qt Creator Dodajte sljedeće vrste tema u Priručnik za proširenje Qt Quick 2.0:

• Qt Creator Tema pregleda, koja opisuje arhitekturu i slučajeve upotrebe vašeg dodatka iz perspektive programera Qt Designer-a.
• API dokumentacija, koja se generira iz komentara u kodu.

Konfiguriranje projekata dokumentacije

Qt Creator Koristite QDoc za pisanje dokumentacije za Eclipse. Za više informacija o korištenju QDoc-a pogledajte QDoc priručnik.

QDoc automatski pronalazi nove teme kada ih smjestite kao .qdoc datoteke u mapu izvora dokumentacije. Međutim, da bi teme bile dostupne čitateljima:

• Dodajte ih u sadržaj u qtcreator-toc.qdoc u.
• Koristite \ingroup zapovijed za automatsko dodavanje u popise tema.
• Koristite \l (link) i \sa (see also) zapovijedi za dodavanje poveznica na njih iz drugih tema.

Izrada mapa i datoteka

Repozitorij qtcreator sadrži izvore za izradu sljedećih dokumenata:

• Qt Creator Priručnik
• Proširivanje priručnika Qt Creator

Izvorni kod za svaki projekt nalazi se u sljedećim podmapama mape projekta Qt Creator:

• \doc\qtcreator\src
• \doc\qtcreatordev\src

Priručnik za proširenje Qt Creator -a preuzima referentnu dokumentaciju API-ja iz izvornika Qt Creator. Dodajte dokumentaciju koda izravno u izvorne datoteke koda. Međutim, možete napisati i pregled API-ja kao zasebnu datoteku .qdoc.

U odgovarajućoj mapi src stvorite podmapu za svoju dokumentaciju. Za svaku temu stvorite zasebnu datoteku.

Vjerojatno je najlakši način kopirati postojeću datoteku, spremiti je kao novu datoteku i izmijeniti je. Na taj način već imate primjere potrebnih dijelova, kao što su naredbe za početak i kraj teme, izjava o autorskim pravima, naredba teme (obično \page), navigacijske poveznice, grupiranje i naslov teme.

Integracija tema u dokumentaciju

Morate integrirati svoje nove teme u priručnike dodavanjem poveznica na njih iz sadržaja i iz drugih relevantnih tema. Najlakši način za to je dodavanje \ingroup naredbi u svaku temu.

U priručniku Qt Creator možete vidjeti trenutne grupe u odjeljcima Kako postupiti i Referenca sadržaja. Možete dodati nove grupe.

Da biste povezali teme s drugim temama, možete koristiti naslov teme.

Na primjer:

\l {Integrating Topics to Documentation}

\sa {Integrating Topics to Documentation}

Ovo radi samo ako su naslovi tema jedinstveni. Također, ako promijenite naslov, poveznica se prekida. Ovaj rizik možete izbjeći dodavanjem \target zapovijed u svoju temu, a zatim povezati na odredište.

Ažuriranje poveznica na sljedeću i prethodnu stranicu

QDoc automatski generira poveznice na prethodnu i sljedeću stranicu u svakom priručniku na temelju popisa u temi pod naslovom All Topics, koja se nalazi u sljedećoj datoteci: \qtcreator\doc\qtcreator\src\qtcreator-toc.qdoc.

Naslov teme koji se koristi za automatsko generiranje navigacijskih poveznica postavlja se kao vrijednost opcije navigation.toctitles u konfiguracijskoj datoteci dokumenta: \doc\qtcreator\config\qtcreator-project.qdocconf.

Kada dodajete nove teme, morate ih dodati ili u sadržaj (TOC) ili u grupu tema (\ingroup) koja se koristi za generiranje popisa u sadržaju (\generatelist).

Dodavanje dokumentacije za neovisne dodatke

Možete razvijati dodatke za Qt Creator u odvojenim repozitorijima. Takvi dodaci trebali bi imati vlastite datoteke pomoći (.qch) koje se instaliraju i registriraju samo ako je dodatak instaliran.

Najlakši način za postavljanje projekta dokumentacije za neovisni dodatak jest kopiranje iz postojećeg repozitorija, a zatim izvršavanje potrebnih izmjena.

Qt Creator Koristite sljedeću shemu imenovanja za priručnike dodataka za samostalne dodatke: Qt Creator <Naziv dodatka> Priručnik dodatka.

Pisanje teksta

Slijedite smjernice u dokumentu Writing Qt Documentation.

Dokumentacija mora biti gramatički ispravan engleski jezik i koristiti standardni oblik pisanog jezika. Nemojte koristiti dijalekte ili žargon. Koristite idiomatičan jezik, tj. izraze koji su karakteristični za engleski jezik. Ako je moguće, zatražite recenziju od izvornog govornika engleskog jezika.

Velika slova u naslovima

Koristite stil naslovnog kapitaliziranja kao za naslove knjiga za sve naslove i podnaslove (\title, \section1, \section2 i tako dalje). Za više informacija pogledajte Korištenje stila naslovnih slova kao u knjigama.

Korištenje slika

Dokumentaciju možete ilustrirati, na primjer, snimkama zaslona, dijagramima i animiranim slikama.

Slijedite smjernice u QUIP 21 | Korištenje slika u Qt dokumentaciji.

Sljedeći odjeljci sadrže neke smjernice i primjere specifične za Qt Creator.

Ikone

Qt dokumentacija objavljena na mreži može se pregledavati u tamnom i svijetlom načinu rada. Kako biste ikone korištene u dokumentaciji učinili vidljivima u oba načina rada, spremite datoteke ikona kao slike u sivim tonovima s prozirnom pozadinom na sljedećoj lokaciji: qtcreator/doc/qtcreator/images/icons.

Možete koristiti skriptu smještenu u qttools/util/recolordocsicons/ za promjenu boje ikona.

Snimanje slika

Spremite slike u PNG ili WebP formatu u mapu projekta Qt Creator u mapi doc/qtcreator/images ili njezinim podmapama.

Prije spremanja PNG slika, optimizirajte ih pomoću alata za optimizaciju slika, kao što je OptiPNG. Da biste ga pokrenuli iz projekta Qt Creator, unesite sljedeću naredbu:

optipng -o 7 -strip all doc/images/<screenshot_name>

Povezivanje na YouTube videozapise

Možete koristiti makro \youtube za povezivanje na video na YouTubeu. HTML dokumenti prikazuju minijaturu videa s gumbom za reprodukciju.

Podrška za makro definirana je u datotekama qtcreator\doc\config\macros.qdocconf i qtcreator\doc\config\macros-online.qdocconf. Za korištenje makra morate spremiti minijaturu videa u mapu qtcreator\doc\qtcreator\images\extraimages\images.

Morate dodati naziv datoteke s minijaturom u datoteku qtcreator-extraimages.qdocconf u mapi \qtcreator\doc\qtcreator\images\extraimages.

Izrada dokumentacije

Koristite QDoc za izgradnju dokumentacije. Izgradite dokumentaciju prije slanja bilo kakvih zakrpa dokumentacije kako biste provjerili njezinu strukturu, sadržaj i valjanost QDoc naredbi. Poruke o pogreškama koje QDoc izdaje općenito su vrlo korisne za otklanjanje poteškoća.

Postavljanje izgradnje dokumentacije

Možete koristiti instaliranu verziju Qt-a za izradu dokumentacije. Sadržaj i formatiranje dokumentacije u QDocu su odvojeni. Konfiguracija dokumentacije, stilski listovi i predlošci mijenjali su se tijekom vremena, stoga se razlikuju između verzija Qt-a i Qt Creator a.

Predlošci koje ćete koristiti definirani su konfiguracijskom datotekom qt5/qtbase/doc/global/qt-html-templates-offline.qdocconf i qt5/qtbase/doc/global/qt-html-templates-online.qdocconf. Preuzimaju se iz Qt izvora dodavanjem sljedećih redaka u datoteku qdocconf:

• include ($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf) za datoteke pomoći.
• include ($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf) za objavljivanje na webu.

Za izgradnju dokumentacije za izvore iz glavne grane qtcreator, upotrijebite skripte za izgradnju definirane u datoteci doc.pri. Dokumentaciju možete izgraditi koristeći ili offline ili online stil. Offline stil se koristi za generiranje HTML datoteka uključenih u datoteke pomoći (.qch), dok se online stil koristi na doc.qt.io.

Korištenje CMakea

Kada se koristi CMake, dokumentacija se gradi u mapi za izgradnju Qt Creator ili u zasebnoj mapi za izgradnju dokumentacije, a ne u mapi projekta.

Za izgradnju dokumentacije pomoću CMakea u zasebnom direktoriju za izgradnju dokumentacije:

1. Nastavite mapu za izgrađene dokumente i prijeđite u nju. Na primjer, C:\dev\qtc-doc-build.
2. U mapi za izgradnju dokumentacije unesite sljedeću naredbu:

   cmake -DWITH_DOCS=ON "-DCMAKE_PREFIX_PATH=<path_to_qt>" <path_to_qtcreator_src>

   Na primjer (sve na jednoj liniji):

   C:\dev\qtc-doc-build>cmake -DWITH_DOCS=ON
       "-DCMAKE_PREFIX_PATH=C:\Qt\6.10.0\msvc2022_64"
       C:\dev\qtc-super\qtcreator

3. Za izgradnju i priručnika Extending Qt Creator Manual, dodajte sljedeću opciju: -DBUILD_DEVELOPER_DOCS=ON
4. Za izgradnju dokumentacije pomoću online stila upotrijebite sljedeću opciju umjesto -DWITH_DOCS=ON: -DWITH_ONLINE_DOCS=ON

   Na primjer:

   C:\dev\qtc-doc-build>cmake -DWITH_ONLINE_DOCS=ON
       -DBUILD_DEVELOPER_DOCS=ON
       -DBUILD_DESIGNSTUDIO=ON
       "-DCMAKE_PREFIX_PATH=C:\Qt\6.10.0\msvc2022_64"
       C:\dev\qtc-super\qtcreator

   Napomena: Ako ste već pokrenuli CMake -DWITH_DOCS=ON u mapi i želite prebaciti se samo na online dokumente u toj mapi, morate ponovno isključiti offline dokumente:

   cmake -DWITH_DOCS=OFF -DWITH_ONLINE_DOCS=ON

5. Unesite sljedeću naredbu za izgradnju dokumentacije kako biste izgradili i HTML dokumente i datoteke pomoći (.qch):

   cmake --build . --target docs

6. Alternativno, za izgradnju samo HTML dokumentacije unesite:

   cmake --build . --target html_docs

HTML datoteke za dokumentaciju generiraju se u sljedećim mapama:

• doc/html/qtcreator
• doc/html/qtcreator-dev
• doc/html/qtcreator-online
• doc/html/qtcreator-dev-online

Datoteke pomoći (.qch) generiraju se u mapi share/doc/qtcreator ili u mapi <application_name>.app/Contents/Resources/doc\ na macOS-u.

HTML datoteke možete pregledavati u pregledniku, a datoteke pomoći u načinu rada Qt Creator Help . Za više informacija o dodavanju datoteka pomoći u Qt Creator pogledajte Qt Creator: Dodavanje vanjske dokumentacije.

Dodatne naredbe za izgradnju

Osim docs i html_docs, možete koristiti sljedeće ciljeve izgradnje:

• html_docs_<doc_config_file_name> - izgradite dokument (qtcreator/qtcreator-dev) u formatu pomoći, ali ne generirajte datoteku pomoći (.qch).
• html_docs_<doc_config_file_name>-online - izgradite dokument (qtcreator/qtcreator-dev) u online formatu.
• qch_docs_<doc_config_file_name> - izgraditi dokument (qtcreator/qtcreator-dev) u formatu pomoći i generirati datoteku pomoći.