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

कमांड लाइन संदर्भ¶

guidedog की कमांड लाइन से दस्तावेज़ परियोजनाओं का प्रबंधन, बिल्ड, पूर्वावलोकन, अनुवाद और रूपांतरण किया जा सकता है।

सामान्य सिंटैक्स¶

guidedog <command> [arguments] [options]
guidedog --version
guidedog --help

निकास कोड¶

तालिका 6 निकास स्थितियाँ¶
निकास कोड	स्थिति
`0`	सफलता: सभी काम पूरे हुए और कोई त्रुटि अनसुलझी नहीं रही।
`1`	बिल्ड या रूपांतरण में त्रुटि हुई, या `-W` ने चेतावनी को त्रुटि माना।
`2`	कमांड लाइन का सिंटैक्स, फ़्लैग या विकल्प गलत है।
`3`	तय संसाधन सीमा पूरी हुई या मेमोरी उपलब्ध नहीं हुई।
`4`	फ़ाइल संबंधी काम या बाहरी कंपाइलर विफल हुआ।
`5`	आंतरिक त्रुटि; निदान में रिपोर्ट करने का तरीका दिया जाता है।
`70`	क्रैश हुआ; पहले प्रकाशित आउटपुट उपलब्ध रहता है।

कमांड का सार¶

तालिका 7 CLI कमांड¶
कमांड	उद्देश्य
`quickstart [DIR]`	नई दस्तावेज़ परियोजना बनाता है, जिसमें टेम्पलेट और कॉन्फ़िगरेशन सीधे संपादित किए जा सकते हैं।
`build [BUILDER] [DIR]`	दस्तावेज़ परियोजना को चुने गए आउटपुट प्रारूप में बनाता है।
`serve [DIR]`	स्थानीय HTTP पूर्वावलोकन सर्वर शुरू करता है और फ़ाइल बदलने पर अपने आप दोबारा बिल्ड करता है।
`clean [DIR]`	बिल्ड से बनी फ़ाइलें और कैश हटाता है।
`convert INPUT`	एक फ़ाइल या मानक इनपुट को सीधे रूपांतरित करता है।
`migrate [conf.py]`	Sphinx की `conf.py` को घोषणात्मक `conf.toml` में बदलता है।
`intl <update\|stat>`	PO अनुवाद कैटलॉग अद्यतन करता है या अनुवाद की प्रगति बताता है।
`formats`	अंतर्निहित रीडर, रेंडरर और प्रारूप-अनुपालन की जानकारी दिखाता है।
`gds <COMMAND>`	Guidedog Discussions के डिज़ाइन अभिलेख और उनका जीवनचक्र संभालता है।

guidedog quickstart¶

परियोजना फ़ोल्डर में conf.toml, index.rst, _templates/ में टेम्पलेट और _static/ में स्टाइल बनाता है:

# Interactive prompt
guidedog quickstart docs

# Non-interactive creation with predefined options
guidedog quickstart docs -q -p "My Project" -a "Author Name" -v 1.0 -l en

विकल्प:

-q: बिना सवाल पूछे कमांड लाइन पर दिए गए मान इस्तेमाल करता है।
-p, --project NAME: परियोजना का प्रदर्शित नाम तय करता है।
-a, --author NAME: लेखक या संगठन का नाम तय करता है।
-v VERSION: छोटा संस्करण नंबर तय करता है, जैसे 1.0।
-r RELEASE: पूरा रिलीज़ पहचानकर्ता तय करता है, जैसे 1.0.0-rc1।
-l LANGUAGE: परियोजना की डिफ़ॉल्ट भाषा तय करता है। डिफ़ॉल्ट मान en है।
--sep: स्रोत को मुख्य फ़ोल्डर में रखने के बजाय अलग source/ और build/ फ़ोल्डर बनाता है।
--suffix EXT: स्रोत दस्तावेज़ का डिफ़ॉल्ट एक्सटेंशन तय करता है। डिफ़ॉल्ट .rst है।

guidedog build¶

स्रोत पढ़ने, विषय-सूची और पार-संदर्भ सुलझाने, तथा अंतिम आउटपुट प्रकाशित करने का काम संभालता है:

# Standard project build
guidedog build html docs
guidedog build pdf docs

# Sphinx-build compatibility syntax
guidedog build -b html docs _build/html
guidedog build -M html docs _build

समर्थित बिल्डर:

html: खोज और नेविगेशन वाला पूरा HTML साइट बनाता है।
dirhtml: dir/index.html जैसे फ़ोल्डर-आधारित HTML URL बनाता है।
singlehtml: सभी दस्तावेज़ एक HTML पृष्ठ में जोड़ता है।
pdf: Typst से PDF पुस्तक बनाता है। इसके उपनाम latex और latexpdf हैं।
text: हर दस्तावेज़ के लिए सादा टेक्स्ट फ़ाइल बनाता है।
gettext: अनुवाद योग्य पाठ को GNU gettext POT टेम्पलेट में निकालता है।
dummy: अंतिम फ़ाइल बनाए बिना दस्तावेज़ ट्री पार्स करता है और संदर्भ सुलझाता है; सिंटैक्स जाँच के लिए उपयोगी है।

बिल्ड के विकल्प:

-a: संशोधन समय की परवाह किए बिना सभी आउटपुट फ़ाइलें लिखता है।
-E: कैश की स्थिति अनदेखी कर वातावरण नए सिरे से बनाता है।
-W: हर चेतावनी को बिल्ड की विफलता मानता है।
--keep-going: -W के साथ भी बाकी दस्तावेज़ों का काम पूरा कर, निकलने से पहले सभी त्रुटियाँ बताता है।
-n: सभी अनसुलझे पार-संदर्भों पर चेतावनी देता है।
-j N / -j auto: दस्तावेज़ पार्स करने के लिए थ्रेड की संख्या तय करता है। auto इसे CPU कोर की संख्या के बराबर रखता है।
-D name=value: इस रन के लिए conf.toml की सेटिंग बदलता है, जैसे -D language=de।
-D table.key=value: html_context जैसी टेबल सेटिंग की एक कुंजी सेट करता है और बाक़ी कुंजियाँ वैसी ही रखता है, जैसे sphinx-build करता है।
-t TAG: only निर्देश के लिए शर्त वाला टैग तय करता है।
-c DIR: conf.toml वाला फ़ोल्डर बताता है।
-C: कोई conf.toml फ़ाइल पढ़े बिना बिल्ड करता है।
-v: विस्तृत मोड में अतिरिक्त जानकारी और समय के आँकड़े दिखाता है।
-q: केवल चेतावनी और त्रुटि दिखाता है।
--color=always|never|auto: टर्मिनल में ANSI रंगों का इस्तेमाल नियंत्रित करता है।
--diagnostics=json: मानक त्रुटि आउटपुट पर मशीन-पठनीय JSON निदान लिखता है।
--budget=MIB: परियोजना होस्ट की मेमोरी सीमा तय करता है। डिफ़ॉल्ट 1024 MiB है।
--memory=ram|disk: मेमोरी बजट खत्म होने पर अपनाई जाने वाली नीति तय करता है।
--untrusted: रॉ एम्बेडेड मार्कअप छोड़ता है और नेटवर्क से लाना बंद करता है। यह क्षमता की नीति है, प्रक्रिया का सैंडबॉक्स नहीं।

guidedog serve¶

स्थानीय HTTP सर्वर और फ़ाइल निगरानी शुरू करता है। स्रोत, टेम्पलेट या संसाधन बदलने पर दोबारा बिल्ड करता है और ब्राउज़र ताज़ा करता है:

# Serve current project on default port (8000)
guidedog serve docs

# Serve on custom port and host
guidedog serve docs --port 9000 --host 0.0.0.0

विकल्प:

-p, --port PORT: स्थानीय पोर्ट। डिफ़ॉल्ट 8000 है।
--host HOST: सर्वर का IP पता। डिफ़ॉल्ट 127.0.0.1 है।

guidedog clean¶

बिल्ड फ़ोल्डर और वातावरण का कैश हटाता है:

guidedog clean docs

guidedog convert¶

परियोजना फ़ोल्डर या कॉन्फ़िगरेशन के बिना फ़ाइल या मानक इनपुट को सीधे बदलता है:

# Convert reStructuredText to HTML
guidedog convert guide.rst --output guide.html

# Convert Markdown to PDF
guidedog convert guide.md --to pdf --output guide.pdf

# Stream conversion from standard input to standard output
cat document.md | guidedog convert - --from commonmark --to html --output -

विकल्प:

-o, --output FILE: आउटपुट फ़ाइल का पथ; - का मतलब मानक आउटपुट है।
--to FORMAT: आउटपुट प्रारूप html, pdf या text है; फ़ाइल नाम से भी पहचाना जा सकता है।
--from FORMAT: स्रोत रीडर rst, commonmark, myst या typst है; इनपुट के एक्सटेंशन से भी पहचाना जा सकता है।
--force: पूछे बिना मौजूदा आउटपुट फ़ाइल बदल देता है।
--strict: किसी भी चेतावनी पर विफल होता है।
--raw=allow|omit: एम्बेड किए गए रॉ कोड की नीति; डिफ़ॉल्ट omit है।
--emit-typst FILE: बीच में बना Typst स्रोत अलग फ़ाइल में लिखता है।

guidedog migrate¶

Sphinx की Python कॉन्फ़िगरेशन फ़ाइल conf.py को घोषणात्मक conf.toml में बदलता है:

# Convert conf.py in-place
guidedog migrate docs/conf.py

# Output to a specific file
guidedog migrate docs/conf.py -o docs/conf.toml --force

विकल्प:

-o FILE: बताए गए पथ पर लिखता है; - से मानक आउटपुट पर लिखता है।
--force: मौजूदा conf.toml को बदल देता है।

guidedog intl¶

बहुभाषी दस्तावेज़ों के अनुवाद कैटलॉग संभालता है:

# Step 1: Extract POT templates
guidedog build gettext docs

# Step 2: Create or update language PO catalogs
guidedog intl update -l de -l fr docs

# Check translation completion percentages
guidedog intl stat -l de docs

intl update के विकल्प:

-l, --language LANG: लक्षित भाषा का कोड; कई भाषाओं के लिए दोहरा सकते हैं।
-p, --pot-dir DIR: निकाले गए POT टेम्पलेट का पथ बताता है।

guidedog formats¶

अंतर्निहित रीडर, रेंडरर, सिंटैक्स हाइलाइटर और मानक परीक्षणों के नतीजे दिखाता है:

guidedog formats

guidedog gds¶

Guidedog Discussions के आर्किटेक्चर प्रस्ताव (RFC) संभालता है:

guidedog gds new "Feature Title" --author="Name"
guidedog gds list --state=prediscussion
guidedog gds show 0003
guidedog gds promote 0003 --dry-run
guidedog gds state 0003 --to=accepted --reason="Consensus reached"
guidedog gds index
guidedog gds check --render
guidedog gds recover --rollback