Увод¶
Пајтон заједница је је покренула пројекат Сфинкс (Sphinx) као генератор техничке документације из изворног кода. Сфинкс користи једноставан језик за означавање, који се зове reStructuredText (RST, ReST, или reST), и конвертује фајлове писане на овом језику у HTML. Током времена је употреба Сфинкса проширена на писање разних врста текстова у којима се поред програмског кода појављују линкови, слике, табеле, итд. Изворни кôд текста који читате је такође писан у reST формату.
Пројекат PetljaDoc се надовезује на Сфинкс и тако проширује синтаксу језика reST за потребе писања курсева и приручника који се објављују на сајту https://petlja.org.
Овде ће бити приказан избор из синтаксе језика reST (са проширењима PetljaDoc), која се до сада показала довољном за писање едукативних садржаја у организацији Фондације Петља. Тамо где се исти ефекат може постићи на више начина, често је изложен само један, и то онај који је одомаћен у Петљи.
Намена и структура овог курса¶
Курс је намењен пре свега ауторима Петљиних курсева и приручника, а може да буде од користи свима који пишу сличне документе у reST формату. Осим курсева и приручника, Петља објављује и збирке алгоритамских задатака и збирке кратких питања, али њихов формат је другачији и (бар за сада) није део овог упутства.
Поглавље Брзи старт садржи примере најчешће коришћене функционалности и одговарајуће синтаксе на језику reST. Ово поглавље може да послужи
за стицање представе шта и како може да се напише, односно убаци у текст (мада не показује све што може да се уради),
за угледање (кôд из примера може лако да се прекопира и прилагоди)
за подсетник ауторима који су се у неком тренутку упознали са потребном синтаксом, али је не знају напамет
Зависно од теме коју покривате у свом курсу или приручнику, поглавље Брзи старт може да буде сасвим довољно за довршавање вашег пројекта.
У наставку овог курса, сва распложива функционалност и пратећа синтакса су објашњени детаљније. На местима где се користе уметнути језици (на пример, LaTeX за записивање математичких и сличних формула, регуларни изрази за задавање одговора који се прихватају као тачни итд.) дати си линкови на екстерне ресурсе.
Треба имати на уму да се ни у једном Петљином курсу (нити другачијем типу издања) не користе све могућности које су овде описане, па нема смисла унапред се детаљно упознавати са свим тим могућностима. Зато се препоручује да поглавља Основе и Програми који се извршавају у веб странама у првом читању погледате само летимично, а да се на детаље враћате по портеби, као на референтни приручник.
У поглављу Основе је детаљније описано основно форматирање текста, стављање текста у табеле и разне оквире, употреба сличица мале висине као делова текста, прављење питања у текстуалним активностима, прављење квизова (питања у текстуалним активностима и квизови имају различиту функционалност, тј. не пишу се и не понашају се исто). Укратко, у поглављу Основе је описана функционалност општег типа, која може да буде потребна у великом броју пројеката.
У поглављу Програми који се извршавају у веб странама је описано како се у документ додају компоненте, у оквиру којих могу да се извршавају скриптови. За такве компоненте описана су и разна подешавања, нпр. да ли корисник може да мења и пише кôд, да ли је омогућено извршавање корак по корак, да ли је предвиђена помоћ у кодирању (делимично решен задатак), да ли корисник може да види жељено понашање скрипта који треба да напише, да ли може да аутоматски тестира свој скрипт итд. Функционалност описана у овом поглаљу се користи углавном у програмерским или мештовитим (интердисциплинарним) курсевима, и то различити делови ове функционалности у различитим курсевима.
Опште препоруке¶
У језику reST је, као и у Пајтону, важна индентација (увлачење). Увлачење за један (карактер) таб није исто као увлачење за одговарајући број размака. Да би се избегла збрка при раду више људи на истом фајлу, препорука Петље је да се таб карактер уопште не користи у RST фајловима (иако reST синтакса то дозвољава). Многи едитори могу да се подесе тако да притисак на тастер Таб интерпретирају као потребан број размака. Подешавањем свог едитора на овај начин, обезбеђујете да нећете унети таб карактер у RST фајл на коме радите.
Увлачење за било који број размака је довољно да се следећи параграф сматра увученим, а сви следећи параграфи који су део исте целине треба да буду увучени за исти број размака (исто као и у Пајтон програмима). Ради конзистентности, лакше читљивости и лакшег премештања делова изворног кода, препорука Петље је да свако увлачење буде за 4 размака. Изузетак су хијерархијске листе, у којима ћемо користити увлачење за по два размака.