ການສ້າງຕົວຢ່າງການສະແດງຜົນພາຍໃນເຄື່ອງ

ທີມງານເອກະສານ Fedora <https://discussion.fedoraproject.org/tag/docs-team> Last review: 2023-03-19
ການສະແດງຜົນຕົວຢ່າງພາຍໃນເຄື່ອງແມ່ນເຄື່ອງມືທີ່ມີຄຸນຄ່າໃນການທົດສອບການປ່ຽນແປງຂອງທ່ານ ເມື່ອເຮັດວຽກຢູ່ໃນສະພາບແວດລ້ອມການຂຽນເອກະສານພາຍໃນເຄື່ອງ. ໃຫ້ລັນສະຄຣິບ docsbuilder ທີ່ມີຢູ່ໃນຄັງເກັບຂໍ້ມູນເນື້ອຫາຂອງ Fedora. ທ່ານສາມາດສ້າງ ແລະ ເປີດເວັບໄຊທີ່ຖືກປະມວນຜົນແລ້ວຢ່າງສົມບູນຢູ່ໃນເຄື່ອງຂອງທ່ານ ເພື່ອເບິ່ງຕົວຢ່າງການປ່ຽນແປງ ກ່ອນທີ່ຈະສົ່ງຄຳຂໍດຶງຂໍ້ມູນ (pull request) ໄປຍັງຄັງເກັບຂໍ້ມູນເນື້ອຫາຂອງ Fedora.

ເມື່ອໃດທີ່ທ່ານຈຳເປັນຕ້ອງໃຊ້ການສະແດງຜົນຕົວຢ່າງພາຍໃນເຄື່ອງ

ເມື່ອເຮັດວຽກກັບສະພາບແວດລ້ອມການຂຽນເອກະສານພາຍໃນເຄື່ອງ, ການສະແດງຜົນຕົວຢ່າງພາຍໃນເຄື່ອງຈະຊ່ວຍໃຫ້ຂັ້ນຕອນການເຮັດວຽກມີຄວາມຄ່ອງຕົວ ໃນການທົດສອບວ່າການປ່ຽນແປງຈະຖືກສະແດງຜົນ ແລະ ເຮັດວຽກແນວໃດໃນບຣາວເຊີຂອງທ່ານ. ເມື່ອທ່ານເຮັດການປ່ຽນແປງ ເຊັ່ນ (ແຕ່ບໍ່ຈຳກັດພຽງແຕ່):

  • ປ່ຽນລິ້ງ ຫຼື ແກ້ໄຂລິ້ງທີ່ເສຍ

  • ປ່ຽນການອ້າງອີງຂ້າມລະຫວ່າງເອກະສານໂດຍໃຊ້ xref

  • ຮວມຫຼາຍໜ້າເຂົ້າເປັນໜ້າດຽວ

  • ອັບເດດຮູບພາບ ຫຼື ແກ້ໄຂຮູບພາບທີ່ບໍ່ສະແດງຜົນ

  • ເພີ່ມຂໍ້ມູນເມຕາ (metadata) ຫຼື ຂໍ້ຄວາມອະທິບາຍຮູບພາບ (alt text)

  • ຈັດລຽງລະດັບຫົວຂໍ້ຄືນໃໝ່ (ຕົວຢ່າງ: h2 ເປັນ h3, h3 ເປັນ h4) ເພື່ອຄວາມສະດວກໃນການອ່ານ ແລະ ຄວາມຕໍ່ເນື່ອງຂອງເນື້ອຫາ

  • ແກ້ໄຂແຖບນຳທາງທີ່ໃຊ້ການບໍ່ໄດ້

  • ຈັດລະບຽບແຖບນຳທາງຄືນໃໝ່

  • ຂຽນໜ້າທີ່ລ້າສະໄໝຄືນໃໝ່

  • ເພີ່ມຄຸນລັກສະນະ (attributes) ຂອງ AsciiDoc

  • ທົດສອບການປ່ຽນແປງຄືນໃໝ່ດ້ວຍ vale linter

ທ່ານຈຳເປັນຕ້ອງໃຊ້ສະຄຣິບໃນການສ້າງ (build scripts) ເພື່ອປະມວນຜົນການປ່ຽນແປງໃຫ້ເປັນໄປຕາມທີ່ຄາດໄວ້ ແລະ ທົດສອບພວກມັນກ່ອນທີ່ທ່ານຈະສົ່ງຄຳຂໍດຶງຂໍ້ມູນ (pull request).

ສະຄຣິບເຫຼົ່ານີ້ເຮັດວຽກແນວໃດ

ສະຄຣິບສ້າງເອກະສານແບບລວມສູນ docsbuilder.sh ຈະສ້າງເວັບໄຊເວີຊັນພາຍໃນເຄື່ອງ, ເຊິ່ງໝາຍເຖິງສ່ວນໜຶ່ງຂອງເວັບໄຊທັງໝົດທີ່ຢູ່ໃນຄັງເກັບຂໍ້ມູນພາຍໃນເຄື່ອງຂອງທ່ານ. ຫຼັງຈາກນັ້ນ, ສະຄຣິບຈະເລີ່ມເຮັດວຽກເວັບເຊີເວີ (webserver) ແລະ ສະແດງຜົນເວັບໄຊຢູ່ທີ່ລິ້ງ: http://localhost:8080/. ການເປີດລິ້ງນີ້ໃນບຣາວເຊີໃດກໍຕາມຈະສະແດງໃຫ້ທ່ານເຫັນຕົວຢ່າງ, ເຊິ່ງຈະສາມາດເບິ່ງໄດ້ຈົນກວ່າທ່ານຈະຢຸດການເຮັດວຽກຂອງໂປຣເຊສ (ກົດ kbd:[Ctrl+C] ໃນເທີມິນໍ).

ກວດສອບ README.md ໃນໜ້າຫຼັກຂອງໂຄງການ ເພື່ອລັນສະຄຣິບທີ່ແນະນຳໃຫ້ໃຊ້.

ວິທີທົດສອບການປ່ຽນແປງ

ເຂົ້າໄປຍັງໄດເຣັກທໍຣີທີ່ໄດ້ໂຄລນ (cloned) ຄັງເກັບຂໍ້ມູນໄວ້, ສ້າງ, ຕິດຕາມ ແລະ ເບິ່ງຕົວຢ່າງເວັບໄຊໂດຍການລັນສະຄຣິບການສ້າງໃນເທີມິນໍ.

$ ./docsbuilder.sh

Pagure ຫຼື ຄັງເກັບຂໍ້ມູນເນື້ອຫາອື່ນໆ ອາດຈະສະແດງສະຄຣິບການສ້າງທີ່ແຕກຕ່າງກັນ.

$ ./builder.sh

ເພື່ອໃຊ້ສະຄຣິບເຫຼົ່ານີ້ ທ່ານຈຳເປັນຕ້ອງຕິດຕັ້ງ Podman ຫາກໃຊ້ Fedora Linux ຫຼື Docker CE ຫາກໃຊ້ macOS.

ການເບິ່ງຕົວຢ່າງຈາກຫຼາຍຄັງເກັບຂໍ້ມູນ

ຫາກວຽກຂອງທ່ານກວມເອົາເນື້ອຫາໃນຫຼາຍຄັງເກັບຂໍ້ມູນ, ເຊັ່ນ: ຍ້ອນວ່າທ່ານ ລິ້ງໄປຫາຄັງເກັບຂໍ້ມູນອື່ນ, ທ່ານສາມາດຂະຫຍາຍການເບິ່ງຕົວຢ່າງໄດ້ໂດຍການເພີ່ມຄັງເກັບຂໍ້ມູນເຂົ້າໃນ site.yml ດັ່ງນີ້:

content:
  sources:
  - url: .
    branches: HEAD
  - url: https://forge.fedoraproject.org/docs/another-repository.git
    branches: main

Correct entries to use can be found from docs-fp-o site.yml.

ການໃຊ້ສະຄຣິບ Antora ແບບປົກກະຕິ

ຫາກທ່ານຕ້ອງການໃຊ້ຂັ້ນຕອນການສ້າງ ແລະ ເບິ່ງຕົວຢ່າງຂອງ Antora ແບບປົກກະຕິ - ໃຫ້ປະຕິບັດຕາມຄຳແນະນຳໃນ ໜ້າເອກະສານຂອງ Antora.

ເມື່ອທ່ານມີ Antora CLI ແລະ Antora Site Generator ແລ້ວ, ທ່ານສາມາດສ້າງ ແລະ ເບິ່ງຕົວຢ່າງໜ້າເວັບໄດ້ໂດຍບໍ່ຕ້ອງໃຊ້ສະຄຣິບຄອນເທນເນີ (container scripts).

ເພື່ອສ້າງໜ້າເວັບຕ່າງໆໃນໄດເຣັກທໍຣີໂຄງການ ໃຫ້ລັນຄຳສັ່ງ:

antora generate site.yml

ຄຳສັ່ງນີ້ຈະສ້າງໄດເຣັກທໍຣີໃໝ່ຊື່ວ່າ public ເຊິ່ງລວມມີໄຟລ໌ທີ່ຈຳເປັນທັງໝົດ. ໃຫ້ເຂົ້າໄປທີ່ນັ້ນ ແລະ ລັນຄຳສັ່ງເຊີເວີ. ທ່ານອາດຈະມີ Python simple server ຢູ່ແລ້ວ, ໃນກໍລະນີນີ້ໃຫ້ລັນ:

python3 -m http.server

ຫຼື ຫາກທ່ານມີພຽງແຕ່ Python 2 ໃນເຄື່ອງຂອງທ່ານ:

python -m SimpleHTTPServer

ມັນຈະເປີດການສະແດງຜົນຕົວຢ່າງພາຍໃນເຄື່ອງທີ່ພອດ (port) 8000.

ຫາກທ່ານມີ cargo (ຕົວຈັດການແພັກເກດຂອງ Rust), ທ່ານກໍສາມາດຕິດຕັ້ງ ແລະ ໃຊ້ miniserve ຫຼື ເຊີເວີອື່ນໆຕາມທີ່ທ່ານຕ້ອງການ.

Want to help? Learn how to contribute to Fedora Docs ›