इस पृष्ठ पर

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

दस्तावेज़ लिखना

Guidedog reStructuredText (.rst) और MyST Markdown (.md) संभालता है। दोनों का एक साझा अर्थपूर्ण दस्तावेज़ ट्री बनता है, जिससे HTML साइट और PDF पुस्तक बनती हैं।

स्रोत भाषा चुनना

डोमेन, जटिल तालिका और विस्तार योग्य निर्देश चाहिए तो reStructuredText चुनें। Markdown सिंटैक्स के साथ Sphinx जैसे निर्देश और रोल चाहिए तो MyST Markdown चुनें।

परियोजना में Markdown, MyST के रूप में पढ़ा जाता है। एक फ़ाइल के guidedog convert रूपांतरण में CommonMark डिफ़ॉल्ट है, जब तक MyST स्पष्ट रूप से न चुनें।

शीर्षक और संरचना

दस्तावेज़ का शीर्षक पृष्ठ की पहचान देता है; खंड पाठ को व्यवस्थित करते हैं। RST में शीर्षक के नीचे चिह्नों की रेखा लगती है; ऊपर भी वैसी रेखा लगा सकते हैं। रेखा शीर्षक से छोटी न हो।

शीर्षक के लिए सुझाए गए चिह्न:

Document Title
==============

Section Heading
---------------

Subsection
~~~~~~~~~~

Sub-subsection
^^^^^^^^^^^^^^

Paragraph Heading
"""""""""""""""""

पूरी परियोजना में शीर्षक के स्तर एक जैसे रखें। MyST Markdown में #, ##, ### इस्तेमाल करें।

पाठ का रूप और इनलाइन मार्कअप

इनलाइन मार्कअप अर्थ बताने के लिए इस्तेमाल करें, केवल सजावट के लिए नहीं:

तालिका 1 इनलाइन मार्कअप

शैली	reStructuredText	MyST Markdown
मोटे अक्षर	**strong text**	**strong text**
ज़ोर / तिरछे अक्षर	*emphasized text*	*emphasized text*
इनलाइन कोड	``inline code``	`inline code`
सबस्क्रिप्ट	:sub:`text`	{sub}`text`
सुपरस्क्रिप्ट	:sup:`text`	{sup}`text`

तारे या बैकटिक को साधारण अक्षर की तरह लिखने के लिए बैकस्लैश से एस्केप करें: \*not italic\*।

सूचियाँ

Guidedog चार तरह की सूचियाँ संभालता है:

बुलेट सूची

* First item
* Second item with multiple lines
  of continuing explanation.
* Third item

क्रमांकित सूची

1. Numbered item
2. Second item
#. Automatically numbered item
#. Next auto-numbered item

परिभाषा सूची

परिभाषा सूची में शब्द और उसका अर्थ साथ रहते हैं। शब्द एक पंक्ति में लिखें और अगली पंक्ति से इंडेंट किया अर्थ दें:

Workspace
   A bounded memory buffer supplied by the caller for document conversion.

Session
   A host-level coordinator that manages memory budgets and document caches.

फ़ील्ड सूची

फ़ील्ड सूची से व्यवस्थित मेटाडेटा और पैरामीटर का वर्णन दें:

:Authors: Jane Doe, John Smith
:Version: 1.2
:Status: Active

कोड ब्लॉक

सिंटैक्स हाइलाइटिंग के लिए code-block या sourcecode इस्तेमाल करें। Guidedog 35 से अधिक प्रोग्रामिंग भाषाएँ संभालता है:

.. code-block:: python
   :linenos:
   :caption: Server entry point
   :emphasize-lines: 2, 4-5

   def main():
       app = create_app()
       app.run(host="0.0.0.0", port=8080)

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

• :linenos:: कोड के साथ पंक्ति नंबर दिखाता है।
• :caption: Title: कोड ब्लॉक के ऊपर या नीचे कैप्शन जोड़ता है।
• :emphasize-lines: 1, 3-5: चुनी हुई पंक्तियों पर ज़ोर देता है।
• :name: label: कोड ब्लॉक को संदर्भ का लक्ष्य देता है।

बाहरी स्रोत फ़ाइल सीधे शामिल करने के लिए literalinclude इस्तेमाल करें:

.. literalinclude:: ../src/server.py
   :language: python
   :lines: 1-25
   :linenos:

सूचना ब्लॉक

सूचना ब्लॉक नोट, चेतावनी और अतिरिक्त सलाह उभारते हैं:

.. note::
   Helpful background context or implementation detail.

.. tip::
   Suggested best practices or workflow shortcuts.

.. important::
   Essential requirements that must not be overlooked.

.. warning::
   Conditions that could lead to unexpected behavior or lost work.

.. caution::
   Potential pitfalls or sensitive operational steps.

.. seealso::
   References to related chapters, specifications, or external guides.

Guidedog danger, error, hint और attention भी संभालता है। अपना शीर्षक देने के लिए admonition इस्तेमाल करें:

.. admonition:: Design Rationale

   Explains why a particular architecture was chosen.

तालिकाएँ

Guidedog सरल, ग्रिड और निर्देशों से बनी तालिकाएँ संभालता है।

सरल तालिकाएँ

सरल तालिका में क्षैतिज रेखाएँ कॉलम की सीमा बताती हैं:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
True   True   True
=====  =====  =======

ग्रिड तालिकाएँ

ग्रिड तालिका में कई पंक्तियों वाले सेल और कई कॉलम या पंक्तियाँ घेरने वाले सेल बन सकते हैं:

+------------------------+------------+----------+
| Header row, column 1   | Column 2   | Column 3 |
+========================+============+==========+
| Cell with multiple     | Second     | Third    |
| paragraphs of text.    | column     | column   |
+------------------------+------------+----------+

सूची से बनी तालिकाएँ

list-table नेस्ट की गई बुलेट सूचियों से तालिका बनाता है। इससे चौड़ी तालिका का स्रोत पढ़ना और संस्करण नियंत्रण में सँभालना आसान होता है:

.. list-table:: Project configurations
   :widths: 25 25 50
   :header-rows: 1

   * - Target
     - Builder
     - Description
   * - Website
     - ``html``
     - Static HTML documentation site
   * - Book
     - ``pdf``
     - Typeset PDF book powered by Typst

CSV तालिकाएँ

csv-table कॉमा से अलग किए मानों से तालिका बनाता है:

.. csv-table:: Comparative metrics
   :header: "Name", "Time (ms)", "Memory (MB)"
   :widths: 40, 30, 30

   "Cold build", 42, 12
   "Incremental", 3, 4

चित्र और आकृतियाँ

चित्र, स्क्रीनशॉट और आरेख जोड़ने के लिए image और figure इस्तेमाल करें:

.. image:: /assets/architecture.png
   :width: 600px
   :align: center
   :alt: System architecture diagram

.. figure:: /assets/flow.png
   :scale: 80%
   :align: center
   :alt: Execution flowchart

   Data flows sequentially through reader, resolver, and renderer.

figure चित्र के साथ कैप्शन और वैकल्पिक संदर्भ लक्ष्य जोड़ता है।

विषय-सूची ट्री से दस्तावेज़ की संरचना

toctree दस्तावेज़ का पदानुक्रम, नेविगेशन मेनू और HTML तथा PDF का पढ़ने का क्रम तय करता है:

.. toctree::
   :maxdepth: 2
   :caption: User Guide
   :numbered:

   installation
   quickstart
   configuration

toctree के सामान्य विकल्प:

• :maxdepth: N: विषय-सूची में शामिल शीर्षकों की गहराई।
• :caption: Title: नेविगेशन प्रविष्टियों के ऊपर दिखने वाला वर्ग शीर्षक।
• :numbered:: अध्याय और शीर्षकों को क्रमांक देता है।
• :titlesonly:: केवल दस्तावेज़ के मुख्य शीर्षक दिखाता है, भीतर के खंड नहीं।
• :hidden:: पाठ में सूची दिखाए बिना पढ़ने का क्रम दर्ज करता है।
• :glob:: tutorials/* जैसे वाइल्डकार्ड से दस्तावेज़ चुनने देता है।

पार-संदर्भ और लिंक

स्पष्ट लक्ष्य लेबल से संदर्भ फ़ाइल के नाम से स्वतंत्र और स्थिर रहता है।

लक्ष्य लेबल और :ref:

शीर्षक, तालिका या चित्र के ठीक पहले लक्ष्य लेबल रखें:

.. _storage-model:

Storage model
-------------

Caller storage is bounded and measured upfront.

परियोजना के किसी भी दस्तावेज़ से इस लक्ष्य का संदर्भ दे सकते हैं:

See :ref:`storage-model` for details.
See :ref:`custom link text <storage-model>`.

:doc: से दस्तावेज़ संदर्भ

एक्सटेंशन छोड़े हुए पथ से दूसरे दस्तावेज़ का लिंक दें:

Read the :doc:`configuration guide <../reference/configuration>` for details.

:term: से शब्द का संदर्भ

glossary से शब्दों की परिभाषा दें:

.. glossary::

   Workspace
      A fixed memory arena allocated by the caller for conversion passes.

   Pass
      An in-memory transformation step operating on the document AST.

:term: रोल से शब्द का लिंक दें:

Conversion runs within an allocated :term:`workspace`.

:download: से फ़ाइल डाउनलोड

फ़ाइल को डाउनलोड फ़ोल्डर में कॉपी कर लिंक बनाता है:

Download the :download:`starter template <files/starter.toml>`.

बाहरी लिंक

बाहरी वेब पते का लिंक दें:

Visit `Typst <https://typst.app>`_ for typography details.

प्रतिस्थापन और शामिल करना

दोबारा इस्तेमाल होने वाला वाक्यांश, चिह्न या चित्र तय करें:

.. |version| replace:: 1.0.0
.. |brand| replace:: **Field Notes**

Welcome to |brand| version |version|.

कई फ़ाइलों में reStructuredText सामग्री साझा करने के लिए:

.. include:: ../shared/warnings.rst

MyST Markdown लिखना

MyST Markdown में फेंस ब्लॉक से वही निर्देश और रोल व्यक्त किए जाते हैं:

# Project overview

Here is a paragraph with **bold text**, *italic emphasis*, and `inline code`.

```{note}
This note is rendered identically to a reStructuredText note directive.
```

```{code-block} python
:caption: Example function
:linenos:

def add(a, b):
    return a + b
```

```{toctree}
:maxdepth: 2
:caption: Navigation

first-chapter
second-chapter
```

See {ref}`storage-model` or consult the {doc}`../reference/configuration`.