Skip to content
Download PDF

booklab_logo BookLab System
(c) 2023 RENware Software Systems

TMPL sablon carte noua

Cuprins:

Sablonul pentru o carte noua

Acesta reprezinta sablonul (template) folosit in procesul de creare a unei carti noi (proces NEWB). Acest sablon contine urmatoarele elemente:

  • sectiunile (documentele) de start ale cartii - pagina de index.md si documentul PDF final, ambele goale dar minim necesare in inceperea cartii

  • scripturile comenzi management carte - reprezinta scripturile cu comenzile necesare pentru managementul si "operarea" acelei carti:

    • generarea temporara (de lucru) a cartii pentru previzualizare
    • generarea si asamblarea finala a cartii
    • pornirea serverului de previzualizare (server local HTTP)
    • monitorizarea fisierelor locale in timpul previzualizarii pentru a detectat eventuale modificari facute de utilizator

  • baza de date a cartii este baza de date cu detaliile unei carti, baza de date ce este referentiata din sectiunea catalogul cartilor. Continutul brut al bazei de date cu catalogul cartilor

Localizarea modulului

Acest modul este localizat in directorul book_<cod_carte> numele acestuia construit in felul urmator:

  • prefixul book_ este un sir de caractere constant
  • sufixul <cod_carte> este reprezentat de atributul (cheia) "code" din baza de date de carti (data/books_catalog.json) iar case-ul = majuscule, minuscule NU CONTEAZA - se va considera (coverti) intodeauna la minuscule (lowercase)

Acest director va fi numit generic <book_directory> in materiale / documentatie.

Scripturile executabile pentru carte

Aceasta sectiune enumera si descrie sumar fisierele ce contin scripturile (comenzile) executabile aferente unei carti. Aceste comenzi sunt aceleasi pentru orice carte (motiv pentru care se gasesc in sablonul de carte).

Fiecare script (comanda) poate primi ca parametru de intrare (si daca il primeste este pozitional si primul) identificatorul cartii sub forma atributului / cheii code din baza de date cu carti (<PROJECT_ROOT>/data/books_catalog.json).

Fisierele ce contin comenzi executabile sunt localizate in radacinta sablonului si au numele de forma bkcmd_... iar extensia corespunzatoare limbajului de programare in care sunt scrise (py, sh, etc). Toate aceste fisiere subt direct executabile (chmod +x) si respecta conventia Bash Linux referitoare la prima linie respectiv "shebang" (#!).

Lista fisierelor cu comenzi executabile (listare in ordine alfanumerica):

bkcmd_assembly_cfg_file.sh
asambleaza fisierul de configurare a cartii din partile componente, vezi sectiunea "Fisierul de configurare a cartii"
bkcmd_gen_final_book.py
wip...tbd...
bkcmd_render_cfg_file.py
randeaza (engl: rendering) fisierul de configurare a cartii (book_mkdocs.yml.tmpl) transformind toate cimpurile Jinja in valorile finale aduse din baza de date a cartii rezultind fisierul book_mkdocs.yml
bkcmd_start_book_preview.py
wip...tbd...
bkcmd_start_book_preview.sh
wip...tbd...

wip page ...UPCOMING new scripts...

Directoarele de lucru

Sablonul cartii contine urmatoarele directoare (ordine alfanumerica):

  • <directory_root> - contine scripturile executabile aferente cartii si fisierul de configurare a acesteia

  • book_config_parts - contine parti (sectiuni) din fisierul de configurare a cartii ce permit o mai usoara modificare a sectiunilor - acestea vor fi asamblate intr-un singur fisier (book_mkdocs.yml)

  • my_book - va contine cartea final generata sub forma de site static utilizabil ca atare (prin copiere in directorul "www root" al serverului HTTP)

  • preview_book - contine generari temporare ale cartiii asamblate si este utilizat in scop de pre-vizualizare a cartii in timpul lucrului la aceasta - ca optiune, directorul este monitorizat de serverul HTTP local de prevzualizare astfel incit modificarile in "sursa cartii" sa fie prezentate live

  • raw_source_docs - contine fisierele "sursa" a cartii (in principiu fisiere Markdown si Jupiter Notebook)

Fisierul de configurare a cartii

Asamblarea fisierului de configurare a cartii

Fisierul de configurare a cartii este format din mai multe fisiere / parti (ce contin sectiuni distincte) ce permit o mai usoara modificare a sectiunilor - acestea vor fi asamblate intr-un singur fisier (book_mkdocs.yml). Procesul de generare a fisierului de configurare comporta mai multe faze:

  • asamblarea fisierului din partile componente si crearea unui fisier care este o forma intermediara de "template Jinja". Acesta contine coduri Jinja ce vor fi inlocuite mai triziu cu valorile reale din baza de date (pe masura ce sunt disponibile)

  • randarea fisierului intermediar "template Jinja" si obtinerea fisierului de configurare FINAL cu informatiile reale

  • cei doi pasi ai procesului sunt reprezentati de comenzi diferite astfel incit pot fi utilizate independent in functie de necesitati

  • Localizarea fisierelor de configurare a cartii

    • fisierul FINAL de configurare: <book_directory>/book_mkdocs.yml
    • fisierul temporar de configurare: <book_directory>/book_mkdocs.yml.tmpl (NOTA: acest fisier este in mod normal sters dupa generarea fisierului final de configurare)

LOCALIZARE: <book_directory>/book_config_parts/cfg_01_head_yml_section.yml

Aceasta sectiune contine partea de informatii generale despre carte (nume, autor) si informatia referitoare la copyright-ul cartii (ce va apare in subsolul acesteia). Aceste informatii sunt sub forma unor cimpuri Jinja ce vor fi actualizate (rendering) la generarea cartii efective.

Informatiile tip sablon Jinja din fisierul de configurare

Aceste informatii sunt prezentate mai jos.Se indica si cheia din fisierul de date JSON aferente:

  • {{ book.short_desc }} == JSON short_desc
  • {{ book.site_author }} == JSON site_author
  • {{ book.copyright }} == JSON copyright

Sectiunea "NAVIGATION" (strutura meniu navigare)

LOCALIZARE: <book_directory>/book_config_parts/cfg_02_nav_yml_section.yml

Aceasta sectiune contine elementele de navigare ce vor apare in navigation bar(s) - top, left si right:

  • denumirile ce vor apare in meniuri si fisierele PDF
  • link-urile catre documentele (paginile) chemate sau catre alte site-uri (URL-uri externe)
  • ordinea de afisare a acestora atit in meniu cit si cuprinsul in documentele PDF asamblate

wip page

-#TODO... UPCOMING with detailed information...

Sectiunea "EXTENSIONS" (extensiile si modulele Python)

LOCALIZARE: <book_directory>/book_config_parts/cfg_03_extension_yml_section.yml

Aceasta sectiune contine partea de module / extensii Python necesare pentru renderingul fisierelor markdown (diverse extensii si add-on-uri la formatul markdoen standard).

wip page

-#TODO... UPCOMING with detailed information...

Sectiunea "WORK DIRECTORIES" (directoarele de lucru)

LOCALIZARE: <book_directory>/book_config_parts/cfg_04_dirs_yml_section.yml

Aceasta sectiune contine numele directoarelor de lucru ale "sistemului mkdocs" cele mai importante fiind directorul de generare temporara (pentru verificare) si directorul de generare si asamblare finala site carte si PDF "bun de tipar"

wip page

-#TODO... UPCOMING with detailed information...

Alte fisiere

In directorul ce contine sablonul cartii se mai gasesc urmatoarele fisiere:

  • CNAME ...#TODO
  • ...#TODO

wip page

-#TODO... UPCOMING...

Last update: October 20, 2023