Guidedog / दस्तावेज़ 0.2.0

टेम्पलेट¶

टेम्पलेट प्रस्तुति तय करता है; स्रोत के पाठ की नकल नहीं करता। Guidedog HTML के लिए Jinja और PDF के लिए Typst इस्तेमाल करता है।

Guidedog के टेम्पलेट परियोजना की सामान्य फ़ाइलें हैं, जिन्हें सीधे देखा और संपादित किया जा सकता है। guidedog quickstart काम में आने वाले टेम्पलेट परियोजना में ही लिखता है:

_templates/layout.html में Jinja से HTML साइट की संरचना तय होती है।
_templates/book.typ में Typst से PDF पुस्तक की पृष्ठ-सज्जा, अक्षर-विन्यास और आवरण तय होते हैं।
_static/guidedog.css और _static/guidedog.js डिफ़ॉल्ट स्टाइल और ब्राउज़र के व्यवहार देते हैं।

टेम्पलेट बाहरी पैकेज या बाइनरी कैश में छिपे नहीं रहते; वे परियोजना में होते हैं। उन्हें संपादित करें, guidedog build से दोबारा बनाएँ और guidedog serve से देखें।

HTML टेम्पलेट¶

Guidedog अंतर्निहित Jinja इंजन से मुख्य layout.html टेम्पलेट रेंडर करता है। पूरा लेआउट एक बड़ी फ़ाइल में रखना ज़रूरी नहीं है। इसे छोटे टेम्पलेट, मैक्रो लाइब्रेरी और कई स्तरों की इनहेरिटेंस में बाँट सकते हैं।

मॉड्यूलर टेम्पलेट संरचना¶

templates_path के फ़ोल्डरों में टेम्पलेट को कई फ़ाइलों और उपफ़ोल्डरों में रख सकते हैं। डिफ़ॉल्ट मान ["_templates"] है:

my-docs/
├── conf.toml
├── index.rst
└── _templates/
    ├── layout.html
    ├── base.html
    ├── partials/
    │   ├── header.html
    │   ├── navigation.html
    │   ├── searchbox.html
    │   └── footer.html
    └── macros/
        └── components.html

Guidedog templates_path के सभी फ़ाइल और उपफ़ोल्डर खोजता है। शामिल या इम्पोर्ट करने का पथ इन्हीं फ़ोल्डरों के सापेक्ष होता है:

कोड सूची 1 _templates/layout.html¶

{% extends "base.html" %}

{% block header %}
  {% include "partials/header.html" %}
{% endblock %}

{% block footer %}
  {% include "partials/footer.html" %}
{% endblock %}

Jinja मैक्रो भी अलग फ़ाइलों में परिभाषित करके ज़रूरत की जगह इम्पोर्ट कर सकते हैं:

कोड सूची 2 _templates/macros/components.html¶

{% macro badge(label, type="info") %}
  <span class="badge badge-{{ type }}">{{ label }}</span>
{% endmacro %}

कोड सूची 3 टेम्पलेट में मैक्रो का इस्तेमाल¶

{% import "macros/components.html" as ui %}
{{ ui.badge("New", type="success") }}

`!layout.html` से थीम इनहेरिट करना¶

डिफ़ॉल्ट थीम के कुछ हिस्से बदलने के लिए पूरा पृष्ठ दोबारा लिखना ज़रूरी नहीं है। Sphinx वाली विस्मयादिबोधक सिंटैक्स से अंतर्निहित लेआउट इनहेरिट कर सकते हैं:

कोड सूची 4 _templates/layout.html¶

{# Inherit Guidedog's built-in layout #}
{% extends "!layout.html" %}

{# Inject custom metadata or web fonts into the document head #}
{% block extrahead %}
  {{ super() }}
  <link rel="stylesheet" href="{{ pathto('_static/custom.css', 1) }}">
{% endblock %}

{# Replace or extend the footer with custom content #}
{% block footer %}
  {% include "partials/footer.html" %}
{% endblock %}

{% extends "!layout.html" %} या {% extends "basic/layout.html" %} से लोडर मूल थीम का टेम्पलेट पढ़ता है, परियोजना की _templates/layout.html को बार-बार नहीं पढ़ता।

बदले गए ब्लॉक में {{ super() }} बुलाने से मूल ब्लॉक का पाठ मिलता है। उसकी नकल किए बिना पहले या बाद में सामग्री जोड़ सकते हैं।

लेआउट ब्लॉक¶

अंतर्निहित layout.html में Sphinx की परंपरा के अनुसार ब्लॉक परिभाषित हैं:

ब्लॉक	उद्देश्य
`doctype`	दस्तावेज़ प्रकार की घोषणा। डिफ़ॉल्ट `<!DOCTYPE html>` है।
`htmltitle`	`<head>` के भीतर `<title>` तत्व।
`linktags`	नेविगेशन और मेटा लिंक: `favicon`, `index`, `search`, `prev`, `next`।
`css`	स्टाइलशीट लिंक और इनलाइन CSS के मूल चर।
`scripts`	खोज इंडेक्स और इंटरैक्टिव सुविधाओं वाले JavaScript टैग।
`extrahead`	फ़ॉन्ट, विश्लेषण या अपने मेटा टैग जोड़ने के लिए `<head>` के अंत की जगह।
`header`	मुख्य नेविगेशन से ठीक पहले का हेडर स्थान।
`relbar1`	नाम, संस्करण, खोज और थीम बदलने वाली ऊपरी नेविगेशन पट्टी।
`rootrellink`	संबंधित लिंक से पहले नेविगेशन में जोड़ने की जगह।
`relbaritems`	नेविगेशन पट्टी में अपने अतिरिक्त आइटम।
`sidebar1`	बाईं नेविगेशन पट्टी का कंटेनर।
`sidebartoc`	`sidebar1` के भीतर विषय-सूची का नेविगेशन ट्री।
`breadcrumbs`	मुख्य पाठ के ऊपर क्रमबद्ध नेविगेशन पथ।
`document`	मुख्य पाठ को घेरने वाला कंटेनर।
`body`	वर्तमान दस्तावेज़ का रेंडर किया HTML पाठ, `{{ body }}`।
`relbar2`	पिछले और अगले अध्याय के लिंक वाला निचला नेविगेशन।
`footer`	कॉपीराइट, अद्यतन समय और स्रोत लिंक वाला पादलेख।
`sidebar2`	वर्तमान पृष्ठ की रूपरेखा दिखाने वाली दाईं पट्टी।

टेम्पलेट खोजना¶

Guidedog conf.toml के templates_path वाले फ़ोल्डर क्रम से खोजता है, फिर अंतर्निहित टेम्पलेट देखता है। नाम इन फ़ोल्डरों के सापेक्ष होते हैं; .. से बाहर नहीं जा सकते।

templates_path की हर फ़ाइल और उपफ़ोल्डर बिल्ड की निर्भरता है। टेम्पलेट जोड़ने, बदलने या हटाने पर guidedog build और guidedog serve बदलाव पहचानकर साइट दोबारा रेंडर करते हैं।

पृष्ठ के वेरिएबल¶

Sphinx के मौजूदा वेरिएबल नाम Guidedog भी रखता है, जिससे थीम के कुछ हिस्से लाए जा सकते हैं।

वेरिएबल	मान
`body`	HTML में दस्तावेज़।
`title`	दस्तावेज़ का शीर्षक।
`pagename`, `docname`	दस्तावेज़ का नाम, जैसे `usage/install`। दस्तावेज़ न होने वाले पेज पर `docname` खाली और `pagename` पेज नाम है: Sphinx की तरह `genindex`, `py-modindex`, `search` या टेम्पलेट पेज का नाम।
`toc`	विषय-सूची वृक्ष से बना HTML नेविगेशन।
`outline`	दस्तावेज़ के खंड HTML में; खंड न हों तो खाली।
`prev`, `next`	पढ़ने के क्रम में पड़ोसी पृष्ठ, `url` (या `link`) और `title` सहित; आरंभ और अंत में पड़ोसी नहीं होता।
`project`, `version`, `release`, `copyright`, `language`	इसी नाम के विकल्प।
`html_title`, `docstitle`	`html_title`; डिफ़ॉल्ट “<project> <release> documentation”।
`html_short_title`, `shorttitle`	`html_short_title`.
`root_doc`, `master_doc`	रूट दस्तावेज़ का नाम।
`pathto_root`	पृष्ठ से साइट के रूट का पथ, जैसे `../`।
`root_url`, `search_url`, `genindex_url`	रूट पृष्ठ, खोज पृष्ठ और सामान्य इंडेक्स के लिंक।
`css_files`, `js_files`	`url` वाली फ़ाइलों की सूची: पहले Guidedog की, फिर `html_css_files` और `html_js_files`।
`logo_url`, `favicon_url`	`_static` के भीतर `html_logo` और `html_favicon`; न दिए हों तो खाली।
`accent`	थीम का रंग `html_theme_options.accent`।
`sourcelink_url`	स्रोत दिखाने पर `_sources` के भीतर दस्तावेज़ का स्रोत; अन्यथा खाली।
`last_updated`	`html_last_updated_fmt` हो तो उस रूप में बिल्ड की तारीख़; अन्यथा खाली।
`show_copyright`, `show_sphinx`, `show_guidedog`, `has_source`, `show_source`	`html_show_*` और `html_copy_source` विकल्प।
`builder`, `file_suffix`	बिल्डर का नाम, जैसे `html`, और पृष्ठ का प्रत्यय।
`html_context` की हर कुंजी	मान और उसका प्रकार Sphinx के Python मानों जैसा है: `false` `{% if %}` में असत्य, संख्या संख्या, ऐरे सूची, और टेबल `conf.toml` के कुंजी क्रम वाला शब्दकोश है। `guidedog migrate` `conf.py` के `html_context` की लिटरल प्रविष्टियाँ लाता है। गणना से प्राप्त मान अपरिभाषित रहते हैं, जिन्हें टेम्पलेट असत्य पढ़ता है।

pathto Sphinx का टेम्पलेट फ़ंक्शन है। pathto("usage/install") दस्तावेज़ पेज और pathto("_static/logo.svg", 1) साइट के नीचे फ़ाइल का URL देता है, वर्तमान पेज के सापेक्ष। singlehtml में दस्तावेज़ एक पेज का खंड है: पहला कॉल वहाँ #document-usage-install और खोज व सूचकांक पर index.html#document-usage-install देता है। genindex या टेम्पलेट पेज जैसे गैर-दस्तावेज़ नाम हर बिल्डर में साइट के मूल पेज हैं।

टेम्पलेट से बने पृष्ठ¶

html_additional_pages Sphinx की तरह केवल टेम्पलेट से पेज बनाता है। कुंजी पेज नाम है और मान templates_path का टेम्पलेट:

कोड सूची 5 conf.toml¶

root_doc = "contents"

[html_additional_pages]
index = "indexcontent.html"
download = "download.html"

पेज टेम्पलेट आम तौर पर layout.html extend करके उसके ब्लॉक भरता है, ताकि रूप बाकी पेजों जैसा हो:

कोड सूची 6 _templates/indexcontent.html¶

{% extends "layout.html" %}
{% block htmltitle %}<title>{{ shorttitle }}</title>{% endblock %}
{% block body %}
  <h1>{{ docstitle|e }}</h1>
  <p><a href="{{ pathto("tutorial/index") }}">Tutorial</a></p>
{% endblock %}

टेम्पलेट गैर-दस्तावेज़ पेज के चर पाता है: pagename पेज नाम (index), title और body खाली हैं। pathto, toc, toctree() और html_context वैसे ही काम करते हैं। html, dirhtml और singlehtml हर बिल्ड में मूल पर <name>.html (html_file_suffix) लिखते हैं। टेम्पलेट या templates_path की किसी फ़ाइल का बदलाव सभी पेज फिर बनाता है।

पृष्ठ कहाँ जाता है और Sphinx से कहाँ अलग है:

समान नाम का पेज दस्तावेज़ की जगह लेता है, जैसे Sphinx में अंत में लिखा जाता है। index = "landing.html" से index.html लैंडिंग पेज होता है; विषय-सूची फिर भी index.rst से आती है। singlehtml में मूल एकल पेज रहता है, टेम्पलेट पेज नहीं लिखा जाता और चेतावनी आती है।
dirhtml पेज genindex.html और search.html के पास download.html में लिखता है; Sphinx download/index.html लिखता है। pathto("download") उसी फ़ाइल का पथ देता है।
नाम साइट के मूल का फ़ाइल नाम हो। लिंक मूल से बनते हैं, इसलिए "sub/page" चेतावनी (build.additional_page) के साथ अस्वीकार है। genindex जैसा मौजूद नाम भी अस्वीकार है; Sphinx वहाँ एक पेज पर दूसरा लिख देता है।
guidedog migrate conf.py से html_additional_pages लाता है।

त्रुटियाँ¶

टेम्पलेट की गलती बिल्ड रोकती है और फ़ाइल, पंक्ति संख्या, पंक्ति तथा सुझाव दिखाती है:

TEMPLATE ERROR                                                  template.error

  _templates/base.html:1

No filter named 'defualt'.

Did you mean the filter 'default'?

अपरिभाषित वेरिएबल Jinja की तरह खाली दिखता है।

अनियंत्रित टेम्पलेट भी क्रैश नहीं, त्रुटि से रुकते हैं: 100 से अधिक syntax स्तर (कोष्ठक, टैग, ऑपरेटर, फ़िल्टर या elif कड़ी), 200 से अधिक मैक्रो, include या recursive लूप स्तर, अथवा 512 KiB से अधिक recursion स्टैक। खुद को रखने वाली सूची Python की तरह [...] दिखती है।

PDF टेम्पलेट¶

PDF पुस्तक Typst से सजती है। _templates/book.typ सामान्य Typst फ़ाइल है जो book फ़ंक्शन देती है। Guidedog पुस्तक सोर्स इस रूप में लिखता है:

#import "/_templates/book.typ": book
#show: book.with(title: ..., author: ..., version: ..., date: ...,
  lang: ..., paper: ..., numbering: ..., logo: ...)
// the chapters, one per document of the root toctree

इसलिए किताब का रूप तय करने वाली हर चीज़ उसी फ़ाइल में है: फ़ॉन्ट, पृष्ठ और हाशिए, शीर्षक, शीर्षक पृष्ठ, पृष्ठ शीर्ष और विषय-सूची।

पैरामीटर¶

पैरामीटर	मान
`title`	`pdf_documents` का `title`; अन्यथा `project`।
`author`	किताब का `author`; अन्यथा `author` विकल्प।
`version`	`release`.
`date`	`\|today\|`: दिया गया `today`; अन्यथा `today_fmt` में बिल्ड की तारीख़।
`lang`	`language`.
`paper`	`"a4"`; `pdf_paper_size` `letter` हो तो `"us-letter"`।
`numbering`	toctree में `numbered` हो तो `true`।
`logo`	`pdf_logo` का पथ; न दिया हो तो अनुपस्थित।
`copyright`	अंतिम प्रकाशन टिप्पणी के लिए `copyright`; इसे स्वीकारने वाले टेम्पलेट को ही दिया जाता है।
`body`	अध्यायों की सामग्री।

टेम्पलेट डिफ़ॉल्ट वाले नए पैरामीटर जोड़ सकता है। quickstart में accent, फ़ॉन्ट serif, sans, mono, पाठ size और page-ref हैं। अंतिम को n => [p. #n] जैसे फ़ंक्शन से सेट करने पर दूसरे पेज के संदर्भ के साथ पेज नंबर आता है।

मॉड्यूलर Typst टेम्पलेट¶

Typst में भी एक ही फ़ाइल की सीमा नहीं है। शैली, मैक्रो और आवरण को _templates/ की अलग .typ फ़ाइलों में बाँटें और #import तथा #include से जोड़ें:

कोड सूची 7 _templates/book.typ¶

#import "cover.typ": title-page
#import "typography.typ": apply-styles

#let book(
  title: "",
  author: "",
  version: "",
  date: "",
  lang: "en",
  paper: "a4",
  numbering: false,
  logo: none,
  body,
) = {
  apply-styles()
  title-page(title: title, author: author, version: version, logo: logo)
  body
}

टेम्पलेट क्या इस्तेमाल कर सकता है¶

Typst पैकेज

#import "@preview/cetz:0.4.2" जैसे पैकेज चलते हैं और पहली बार डाउनलोड होते हैं। केवल डिस्क के पैकेज से बनाने के लिए pdf_packages = "offline" सेट करें।

फ़ॉन्ट

typst की तरह सिस्टम फ़ॉन्ट उपलब्ध हैं। pdf_font_paths से फ़ोल्डर जोड़ें, या pdf_fonts = "embedded" से केवल Typst के अंतर्निहित फ़ॉन्ट चुनें, ताकि पुस्तक बाइट-दर-बाइट दोहराई जा सके।

प्रीऐम्बल

pdf_preamble उस Typst फ़ाइल का नाम है जो #show: book के बाद आती है। अपना टेम्पलेट बनाए बिना कुछ set और show नियम देने के लिए ठीक है।

दस्तावेज़ में Typst

दस्तावेज़ reStructuredText और Markdown हैं; Typst फ़ाइलें दस्तावेज़ नहीं। पुस्तक में Typst मार्कअप देने के लिए raw ब्लॉक लिखें, जिसे वेब पेज छोड़ देते हैं:

.. raw:: typst

   #align(center)[#text(size: 14pt)[Only in the book]]

.. only:: pdf भी सामान्य सामग्री केवल किताब में रखता है।

Typst की त्रुटि पर बिल्ड फ़ाइल और पंक्ति बताता है, चाहे टेम्पलेट में हो या बनी पुस्तक में। हर PDF का सोर्स _build/pdf/sources/<pdf-filename>.typ है; reference-en.pdf का sources/reference-en.pdf.typ। एक पुस्तक वाला बिल्ड _build/pdf/book-<language>.typ की जाँच प्रति भी रखता है। विफलता कुछ प्रकाशित नहीं करती; सोर्स त्रुटि में बताए _build/.doctrees/failed पथ पर रहता है। कई पुस्तकों के विफल सोर्स अलग हैं।

नया टेम्पलेट लिखना¶

quickstart के टेम्पलेट से शुरू करें; उनमें हर हिस्से का उपयोग है:

डिफ़ॉल्ट स्टाइलशीट वाला layout.html मार्कअप रखें या उसके साथ _static/guidedog.css भी बदलें।
दोहराए हिस्से अलग फ़ाइल में ले जाकर include करें, या base.html बनाकर layout.html में extends करें।
किताब के लिए book के नियम बदलें या उसी नाम और पैरामीटर का नया फ़ंक्शन लिखें।

संपादन में guidedog serve से प्रीव्यू देखें। स्रोत सहेजकर ब्राउज़र रिफ़्रेश करें; सर्वर बदले इनपुट फिर बिल्ड करके पृष्ठ भेजता है।