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 s ostatkom 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 repozitoriju:

• Uvodne teme, koje opisuju svrhu vašeg dodatka iz perspektive korisnika Qt Creator.
• Tutorijali, koji opisuju kako kreirati 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.

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

• 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 QDoca 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, morate ih također dodati u sadržaj, koristeći \ingroup zapovijed za automatsko dodavanje u popise tema, ili upotrijebite \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
• Qt Design Studio Priručnik

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

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

Priručnik za Qt Creator i priručnik za Qt Design Studio dijele neke teme o razvoju aplikacija za Qt Quick, pisanju i otklanjanju pogrešaka u kodu, pregledavanju QML datoteka i slično.

Priručnik Extending Qt Creator ima vlastite izvore. Osim toga, uvozi referentnu dokumentaciju API-ja iz izvornog koda Qt Creator. Dodajte dokumentaciju koda izravno u izvorne datoteke koda. Međutim, pregled API-ja također možete napisati kao zasebnu .qdoc datoteku.

Stvorite podmapu za svoju dokumentaciju u odgovarajućoj mapi src. Stvorite zasebnu datoteku za svaku temu.

Vjerojatno je najlakši način kopirati postojeću datoteku, spremiti je kao novu datoteku i izmijeniti je. Na taj način već imate uzorke 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. Osim toga, upotrijebite \previouspage i \nextpage naredbe za dodavanje navigacijskih poveznica između tema.

Za povezivanje na temu možete koristiti naslov teme. Na primjer:

\l {Integrating Topics to Documentation}

\sa {Integrating Topics to Documentation}

\previouspage {Integrating Topics to Documentation}

Ovo funkcionira samo ako su naslovi tema jedinstveni. Također, ako promijenite naslov, poveznica će se prekinuti. Taj rizik možete izbjeći dodavanjem \target naredbu svojoj temi, a zatim povezati na odredište.

Prikazivanje i skrivanje informacija

Qt Design Studio koristi samo podskup dodataka za Qt Creator i ima vlastite posebne dodatke. Njihovi priručnici imaju različitu strukturu i sadržaj, pa su u oba priručnika potrebne samo neke izvorske datoteke. Sve datoteke iz \doc\qtdesignstudio\ isključene su iz izgradnje priručnika za Qt Creator.

Ako bi QDoc analizirao sve izvore za priručnik Qt Creator prilikom izgradnje priručnika Qt Design Studio, generirao bi HTML datoteke za svaku temu i uključio te datoteke i sve slike na koje se one pozivaju u datoteke za kompilaciju pomoći Qt Design Studio. To bi nepotrebno povećalo veličinu baze podataka pomoći Qt Design Studio i zaprljalo indeks pomoći referencama na datoteke koje zapravo nisu navedene u sadržaju priručnika Qt Design Studio. Kako bi se to izbjeglo, neke su datoteke isključene iz izgradnji priručnika Qt Design Studio.

Isključivanje izvornog koda iz izrade priručnika Qt Design Studio

Mapu za isključivanje iz izgradnje priručnika Qt Design Studio navodi se kao vrijednost opcije excludedirs u \doc\qtdesignstudio\config\qtdesignstudio.qdocconf.

Vrijednosti opcije trebate uređivati samo ako želite prikazati ili sakriti sav sadržaj mape. Na primjer, ako dodate podršku za Qt Creator dodatak koji prije nije bio podržan u Qt Design Studio, trebali biste iz vrijednosti ukloniti mapu koja sadrži dokumentaciju za dodatak.

Za prikrivanje ili prikazivanje pojedinačnih tema unutar pojedinačnih datoteka .qdoc, potrebno je premjestiti datoteke u izvoru Qt Creator Manual (\doc\qtcreator\src) u izuzete mape ili iz njih.

Na primjer, ako bi se dodala podrška za iOS, trebali biste provjeriti je li informacija o podršci za iOS primjenjiva na Qt Design Studio Manual. Ako jest, trebali biste ukloniti sljedeći redak iz vrijednosti excludedirs:

../../src/ios \

Zatim biste koristili defines kako biste sakrili sve informacije specifične za Qt Creator iz izvornog datoteka u mapi.

Ako mapa sadrži neke datoteke potrebne u oba priručnika i neke koje su potrebne samo u priručniku za Qt Creator, potonje se nalaze u podmapi nazvanoj creator-only, koja je isključena iz izrada priručnika za Qt Design Studio.

Ako u \doc\qtcreator\src dodate novu mapu koja vam nije potrebna u priručniku Qt Design Studio, putanju i naziv mape dodajte kao vrijednost excludedirs.

Skrivanje teksta iz HTML datoteka

Definicija qtcreator specificirana je kao vrijednost defines varijabla u konfiguracijskoj datoteci Qt Creator QDoc, \doc\qtcreator\config\qtcreator-project.qdocconf. Koristite je kao vrijednost \ifQt Creator naredbe u priručniku za Qt Design Studio. Koristi se za prikrivanje specifičnih informacija o Qt Creator iz generiranih HTML datoteka prilikom izrade priručnika za .

Definicija qtdesignstudio navodi se kao vrijednost varijable defines u konfiguracijskoj datoteci Qt Design Studio Manual, qtcreator\doc\qtdesignstudio\config\qtdesignstudio.qdocconf. Koristite je s naredbom \if u izvorima Qt Creator Manual kako biste sakrili informacije specifične za Qt Design Studio iz generiranih HTML datoteka prilikom izrade Qt Creator Manual.

Možete koristiti \else zapovijed za prikaz različitog teksta ovisno o tome koji se priručnik gradi.

Završite uvjetni tekst s \endif naredbu.

Na primjer, terminologija oko uređivača koda različita je u priručnicima Qt Creator i Qt Design Studio, pa se prikazuje različiti tekst ovisno o tome koji se priručnik gradi:

\li \l{Writing Code}

    \if defined(qtdesignstudio)
    The \l{Code} view offers services, such as semantic highlighting,
    syntax checking, code completion, code indentation, and in-line
    error indicators while you are typing.
    \else
    Writing, editing, and navigating in source code are core tasks in
    application development. Therefore, the code editor is one of the
    key components of \QC. You can use the code editor in the
    \uicontrol Edit mode.
    \endif

Pisanje o specifičnim značajkama Qt Design Studio a

Qt Design Studio Specifični dodatci i značajke opisani su u skupu izvornika dokumenata smještenih u mapi \doc\qtdesignstudio\src.

Spremite snimke zaslona i druge ilustracije u \qtdesignstudio\images.

Ako dodate nove teme u Qt Design Studio priručnik, dodajte poveznice na njih u sadržaj u qtdesignstudio-toc.qdoc.

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ćim datotekama:

• Qt Creator: \qtcreator\doc\qtcreator\src\qtcreator-toc.qdoc
• Qt Design Studio: \qtcreator\doc\qtdesignstudio\src\qtdesignstudio-toc.qdoc

Naslov teme koji se koristi za automatsko generiranje navigacijskih poveznica postavlja se kao vrijednost opcije navigation.toctitles u konfiguracijskoj datoteci dokumenta:

• Qt Creator: \doc\qtcreator\config\qtcreator-project.qdocconf
• Qt Design Studio: \doc\qtdesignstudio\config\qtdesignstudio.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).

U priručniku " Qt Creator Manual" možete vidjeti trenutačne grupe u odjeljcima " How To " i "Reference" sadržaja (TOC). Možete dodati nove grupe.

Dodavanje dokumentacije za neovisne dodatke

Možete razvijati Qt Creator dodatke u odvojenim repozitorijima. Takvi dodaci trebaju 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 i zatim izvršavanje potrebnih izmjena.

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

Pisanje teksta

Slijedite smjernice za pisanje Qt dokumentacije.

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 pregled od izvornog govornika engleskog jezika.

Velika početna 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 velikih slova za knjige.

Korištenje slika

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

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

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

Ikone

Qt Design Studio Q t 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će lokacije, ovisno o tome koriste li se u oba priručnika ili samo u priručniku za Qt Quick:

• qtcreator/doc/qtcreator/images/icons Qt Creator - koristi se u priručniku za Qt Quick 2.
• qtcreator/doc/qtdesignstudio/images/icons - koriste se samo u priručniku Qt Design Studio.

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

Siguravanje slika

Spremite slike u PNG ili WebP formatu u mapu projekta Qt Creator u mapi doc/qtcreator/images ili doc/qtdesignstudio/images ili u njihove 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 dokumentacija prikazuje 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 qtcreator\doc\qtcreator\images\extraimages\images.

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

Ako ćete video povezati samo iz priručnika Qt Creator ili priručnika Qt Design Studio, morat ćete samo dodati naziv datoteke s minijaturom u datoteku extraimages.qdocconf za taj projekt.

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 rješavanje problema.

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 koji se koriste 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 izvornog koda dodavanjem sljedećih redaka u datoteku qdocconf:

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

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

Korištenje CMakea

Kod korištenja CMakea, dokumentacija se gradi u mapi za izgradnju Qt Creator ili u zasebnoj mapi za izgradnju dokumentacije, a ne u mapi projekta.

Da biste dobili ispravan naziv proizvoda i verziju prilikom izgradnje priručnika za Qt Design Studio, morate pokrenuti CMake s opcijom BUILD_DESIGNSTUDIO.

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

1. Napravite 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.4.0\msvc2019_64"
       C:\dev\qtc-super\qtcreator

3. Za izgradnju i priručnika Extending Qt Creator, dodajte sljedeću opciju: -DBUILD_DEVELOPER_DOCS=ON
4. Za izgradnju i priručnika Extending Qt Design Studio, dodajte sljedeću opciju: -DBUILD_DESIGNSTUDIO=ON

   Na primjer:

   C:\dev\qtc-doc-build>cmake -DWITH_DOCS=ON -DBUILD_DEVELOPER_DOCS=ON
       -DBUILD_DESIGNSTUDIO=ON
       "-DCMAKE_PREFIX_PATH=C:\Qt\6.4.0\msvc2019_64"
       C:\dev\qtc-super\qtcreator

   Za izgradnju dokumentacije pomoću online stila, upotrijebite sljedeću opciju umjesto xml-ph-0000@dee
5. 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.4.0\msvc2019_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

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

   cmake --build . --target docs

7. 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/qtdesignstudio
• doc/html/qtcreator-online
• doc/html/qtcreator-dev-online
• doc/html/qtdesignstudio-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 pregledati u pregledniku, a pomoćne datoteke u načinu rada Qt Creator Help . Za više informacija o dodavanju pomoćnih datoteka u Qt Creator pogledajte 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/qtdesignstudio) u formatu pomoći, ali ne generirajte datoteku pomoći (.qch).
• html_docs_<doc_config_file_name>-online - izgraditi dokument (qtcreator/qtcreator-dev/qtdesignstudio) u online formatu.
• qch_docs_<doc_config_file_name> - izgradite dokument (qtcreator/qtcreator-dev/qtdesignstudio) u formatu pomoći i generirajte datoteku pomoći.