การร่วมพัฒนาเอกสารของ HEMMS¶

คู่มือนี้ครอบคลุมวิธีเพิ่มและแก้ไขหน้าในไซต์เอกสารของ HEMMS ซึ่ง build ด้วย MkDocs Material

สิ่งที่ต้องมีก่อน¶

ติดตั้ง toolchain ของเอกสาร:

make docs-install

คำสั่งนี้ติดตั้ง MkDocs Material และปลั๊กอินที่จำเป็นทั้งหมดเข้าสู่สภาพแวดล้อม Python ปัจจุบันของคุณ หากคุณต้องการความแยกตัว ให้ใช้ virtual environment:

python3 -m venv .venv-docs
source .venv-docs/bin/activate
make docs-install

การพรีวิวบนเครื่อง¶

เริ่ม dev server แบบ live-reload:

make docs-serve

เปิด http://localhost:8000 ในเบราว์เซอร์ของคุณ การแก้ไขไฟล์ .md ใด ๆ หรือ mkdocs.yml จะทริกเกอร์การ rebuild และรีเฟรชเบราว์เซอร์โดยอัตโนมัติ

การเพิ่มหน้าใหม่¶

1. สร้างไฟล์ Markdown ในโฟลเดอร์ย่อย docs/ ที่เหมาะสม:

   touch docs/modules/criticality/faq.md
   

2. เพิ่ม YAML frontmatter ที่ด้านบน:

   ---
   title: Criticality FAQ
   description: Frequently asked questions about the criticality module
   ---
   

3. เขียนเนื้อหาของคุณโดยใช้ Markdown มาตรฐาน

4. ลงทะเบียนหน้าใน mkdocs.yml ใต้ส่วน nav::

   nav:
     - Modules:
       - Equipment Criticality:
         - modules/criticality/index.md
         - FAQ: modules/criticality/faq.md   # <-- add here
   

5. ตรวจผลลัพธ์ที่ http://localhost:8000

ธรรมเนียมการเขียน¶

หัวเรื่อง¶

ใช้ # สำหรับชื่อหน้า (หนึ่งหน้าต่อหนึ่งอัน), ## สำหรับส่วนหลัก และ ### สำหรับส่วนย่อย MkDocs สร้างสารบัญจากหัวเรื่อง

Admonition¶

ใช้ admonition เพื่อเน้นข้อมูลสำคัญ:

!!! info "Good to know"
    This is an informational callout.

!!! warning
    This warns the reader about a potential issue.

!!! tip "Pro tip"
    A helpful suggestion for advanced users.

!!! danger "Breaking change"
    Something that could cause data loss or downtime.

ชนิดที่ใช้ได้: note, abstract, info, tip, success, question, warning, failure, danger, bug, example, quote

admonition แบบยุบได้ใช้ ??? แทน !!!:

??? example "Click to expand"
    Hidden content revealed on click.

Code block¶

ระบุภาษาเพื่อไฮไลต์ syntax:

```python
class MyModel(models.Model):
    _name = 'my.model'
    name = fields.Char(string='Name', required=True)
```

เพิ่มชื่อให้กับ code block:

```python title="models/my_model.py"
class MyModel(models.Model):
    _name = 'my.model'
```

ไฮไลต์บรรทัดที่ระบุ:

```python hl_lines="2 3"
class MyModel(models.Model):
    _name = 'my.model'
    name = fields.Char(string='Name')
```

ภาพหน้าจอและรูปภาพ¶

วางรูปภาพในโฟลเดอร์ docs/assets/ และอ้างอิงด้วย path แบบสัมพัทธ์:

![Equipment form with criticality badge](../assets/equipment-form-criticality.png)

ใส่ alt text ที่อธิบายได้เสมอ รูปภาพจะแสดงด้วยปลั๊กอิน glightbox — การคลิกที่รูปภาพจะเปิด overlay แบบ lightbox

การเชื่อมโยงข้ามหน้า¶

ใช้ path แบบสัมพัทธ์จากไฟล์ปัจจุบัน:

See the [Equipment Criticality module](../modules/criticality/index.md) for details.

เชื่อมไปยังส่วนที่ระบุโดยใช้ anchor ของหัวเรื่อง:

See [SLA Configuration](../modules/workflow/configuration.md#sla-settings).

แท็บ¶

ใช้แท็บเนื้อหาสำหรับคำแนะนำเฉพาะแพลตฟอร์ม:

=== "Private Hospital"

    ```bash
    make up-private
    make install-private
    ```

=== "Government Hospital"

    ```bash
    make up-gov
    make install-gov
    ```

Definition list¶

ใช้สำหรับรายการแบบอภิธานศัพท์:

BME
:   Biomedical Engineering — the department responsible for medical equipment.

SLA
:   Service Level Agreement — the maximum time allowed for each repair stage.

การ build สำหรับ production¶

เพื่อตรวจสอบว่าไซต์ build ได้โดยไม่มี warning:

make docs-build

คำสั่งนี้รัน mkdocs build --strict ซึ่งล้มเหลวเมื่อมีลิงก์ที่เสียหรือ warning การกำหนดค่าใด ๆ ผลลัพธ์ไปยังไดเรกทอรี site/ (ถูก git ignore)

การส่งการเปลี่ยนแปลง¶

1. สร้าง feature branch:

   git checkout -b docs/my-topic
   

2. ทำการเปลี่ยนแปลงของคุณและตรวจสอบบนเครื่องด้วย make docs-serve

3. รัน strict build เพื่อจับปัญหา:

   make docs-build
   

4. Commit และ push:

   git add docs/ mkdocs.yml
   git commit -m "docs: add my-topic documentation"
   git push -u origin docs/my-topic
   

5. เปิด pull request CI workflow จะ build เอกสารและรายงานข้อผิดพลาดใด ๆ