ເອກະສານ¶
Tip
ເອກະສານຢູ່ໃນເວັບໄຊທ໌ນີ້ຖືກຂຽນເປັນ ReStructuredText, ຫຼື RST ໂດຍຫຍໍ້. ກະລຸນາກວດເບິ່ງ RST Primer ຖ້າທ່ານບໍ່ຄຸ້ນເຄີຍກັບ RST.
ໜ້ານີ້ຈະແນະນຳທ່ານຜ່ານການຂຽນເອກະສານທີ່ດີສຳລັບໂຄງການ UBports ທີ່ສາມາດນຳສະເໜີຢູ່ໃນເວັບໄຊທ໌ນີ້.
ຄຳແນະນຳກ່ຽວກັບເອກະສານ¶
ກົດລະບຽບເຫຼົ່ານີ້ຄວບຄຸມວິທີທີ່ທ່ານຄວນຂຽນເອກະສານເພື່ອຫຼີກເວັ້ນບັນຫາກັບຮູບແບບ, ການຈັດຮູບແບບ ຫຼື ການເຊື່ອມຕໍ່.
ຫົວຂໍ້¶
ທຸກໜ້າຕ້ອງມີຫົວຂໍ້ເອກະສານທີ່ຈະສະແດງຢູ່ໃນສາລະບານ (ແຖບດ້ານຊ້າຍ) ແລະ ຢູ່ເທິງສຸດຂອງໜ້າ.
Titles should be "sentence cased" rather than "Title Cased". For example:
Incorrect casing:
Writing A Good Bug Report
Correct casing:
Writing a good bug report
Correct casing when proper nouns are involved:
Installing Ubuntu Touch on your phone
ບໍ່ມີຄຳນິຍາມດຽວຂອງການໃຊ້ຕົວພິມໃຫຍ່ໃນຫົວຂໍ້ທີ່ທຸກຄົນປະຕິບັດຕາມ, ແຕ່ການໃຊ້ຕົວພິມໃຫຍ່ແບບປະໂຫຍກແມ່ນງ່າຍ. ນີ້ຊ່ວຍຮັກສາການໃຊ້ຕົວພິມໃຫຍ່ໃນສາລະບານໃຫ້ສອດຄ່ອງກັນ.
ຫົວຂໍ້ໜ້າຖືກຂີດກ້ອງດ້ວຍເຄື່ອງໝາຍເທົ່າກັບ. ຕົວຢ່າງ, markup ສຳລັບ ການລາຍງານບັກ (Bug reporting) ລວມມີຫົວຂໍ້ຕໍ່ໄປນີ້:
Bug reporting
=============
ສັງເກດວ່າ:
ຫົວຂໍ້ເປັນຕົວພິມໃຫຍ່ແບບປະໂຫຍກ
ຫົວຂໍ້ຖືກຂີດກ້ອງດ້ວຍເຄື່ອງໝາຍເທົ່າກັບ
ເສັ້ນຂີດກ້ອງກວມເອົາຫົວຂໍ້ທັງໝົດໂດຍບໍ່ເກີນ
ຕົວຢ່າງຫົວຂໍ້ທີ່ບໍ່ຖືກຕ້ອງລວມມີ:
ການໃຊ້ຕົວພິມໃຫຍ່ບໍ່ຖືກຕ້ອງ
Bug Reporting =============
ເສັ້ນຂີດກ້ອງສັ້ນເກີນໄປ
Bug reporting =====
ເສັ້ນຂີດກ້ອງຍາວເກີນໄປ
Bug reporting ================
ຫົວຂໍ້ຍ່ອຍ¶
ມີຫົວຂໍ້ຍ່ອຍຫຼາຍລະດັບທີ່ທ່ານສາມາດວາງໄວ້ໃນໜ້າ. ລະດັບເຫຼົ່ານີ້ຖືກສະແດງຢູ່ທີ່ນີ້ຕາມລຳດັບ:
Page title
==========
Level one
---------
Level two
^^^^^^^^^
Level three
"""""""""""
ກະລຸນາຫຼີກເວັ້ນການໃຊ້ຫຼາຍກວ່າສີ່ລະດັບ. ຖ້າທ່ານຄິດວ່າທ່ານຕ້ອງການລະດັບເພີ່ມເຕີມ, ມັນເປັນສັນຍານທີ່ດີວ່າເອກະສານຄວນຖືກແບ່ງອອກເປັນຫຼາຍໜ້າ. ນອກຈາກນັ້ນ, ສະບັບເວັບຂອງເອກະສານສະແດງພຽງແຕ່ສີ່ລະດັບໃນສາລະບານຂອງມັນ.
ສາລະບານ¶
ຖ້າທ່ານເພີ່ມໜ້າໃໝ່, ທ່ານຕ້ອງເພີ່ມມັນເຂົ້າໃນສາລະບານເຊັ່ນກັນ. ທ່ານສາມາດເຮັດສິ່ງນີ້ໄດ້ໂດຍການເພີ່ມໜ້າເຂົ້າໃນໄຟລ໌ index.rst ໃນໄດເຣັກທໍຣີດຽວກັນກັບບ່ອນທີ່ທ່ານສ້າງມັນ. ຕົວຢ່າງ, ຖ້າທ່ານສ້າງໄຟລ໌ທີ່ມີຊື່ວ່າ "newpage.rst", ທ່ານຈະເພີ່ມແຖວທີ່ໝາຍດ້ວຍເຄື່ອງໝາຍ (> ) ໃນ index ທີ່ໃກ້ທີ່ສຸດ:
.. toctree::
:maxdepth: 1
:name: example-toc
oldpage
anotheroldpage
> newpage
ລຳດັບມີຄວາມສຳຄັນ. ຖ້າທ່ານຕ້ອງການໃຫ້ໜ້າຂອງທ່ານປະກົດຢູ່ໃນຕຳແໜ່ງສະເພາະໃນສາລະບານ, ໃຫ້ວາງມັນໄວ້ບ່ອນນັ້ນ. ໃນຕົວຢ່າງກ່ອນໜ້ານີ້, newpage ຈະຖືກເພີ່ມເຂົ້າໃນຕອນທ້າຍຂອງສາລະບານນີ້.
ການຍ້າຍໜ້າ¶
ບາງຄັ້ງມັນຈຳເປັນຕ້ອງຍ້າຍໜ້າຈາກບ່ອນໜຶ່ງໃນເອກະສານໄປຫາບ່ອນອື່ນ. ໂດຍທົ່ວໄປແລ້ວ ນີ້ແມ່ນເພື່ອປັບປຸງການໄຫຼຂອງເອກະສານ: ຕົວຢ່າງ, ມັນສົມເຫດສົມຜົນກວ່າສຳລັບໜ້າທີ່ຈະມາຫຼັງຈາກໜ້າທີ່ທ່ານຫາກໍເພີ່ມໃນພາກສ່ວນອື່ນ.
ຢ່າງໃດກໍຕາມ, ຄົນເຊື່ອມຕໍ່ກັບເອກະສານຂອງພວກເຮົາຈາກຫຼາຍແຫຼ່ງທີ່ພວກເຮົາບໍ່ໄດ້ຄວບຄຸມ. ບລັອກ, ເວັບໄຊທ໌, ແລະ ເວັບໄຊທ໌ເອກະສານອື່ນໆສາມາດນຳພາຄົນມາທີ່ນີ້ໂດຍໃຊ້ລິ້ງທີ່ພວກເຂົາອາດຈະບໍ່ເຄີຍອັບເດດ. ມັນເປັນປະສົບການທີ່ຂີ້ຮ້າຍທີ່ຈະຕິດຕາມລິ້ງຈາກເວັບໄຊທ໌ອື່ນ ແລະ ໄປຮອດໜ້າ 404, ໂດຍຖືກບັງຄັບໃຫ້ຄົ້ນຫາດ້ວຍຕົນເອງໃນເອກະສານຂອງພວກເຮົາ.
ພວກເຮົາໃຊ້ເຄື່ອງມືທີ່ມີຊື່ວ່າ Rediraffe ເພື່ອຫຼີກເວັ້ນປະສົບການທີ່ບໍ່ດີດັ່ງກ່າວ. Rediraffe ສ້າງໜ້າການປ່ຽນເສັ້ນທາງ, ເຊິ່ງສາມາດສົ່ງຜູ້ໃຊ້ຈາກລິ້ງເກົ່າທີ່ບໍ່ຖືກຕ້ອງໄປຫາລິ້ງໃໝ່ທີ່ເປັນປະໂຫຍດ. ກະລຸນາສ້າງລິ້ງການປ່ຽນເສັ້ນທາງເມື່ອປ່ຽນຊື່ໜ້າ ຫຼື ຍ້າຍໜ້າພາຍໃນໂຄງສ້າງໄດເຣັກທໍຣີຂອງເອກະສານ. ລິ້ງການປ່ຽນເສັ້ນທາງຖືກສ້າງຂຶ້ນໂດຍການວາງຊື່ໄຟລ໌ຂອງເອກະສານເກົ່າ ແລະ ຊື່ໄຟລ໌ຂອງເອກະສານໃໝ່, ທຽບກັບຮາກຖານຂອງເອກະສານ, ໃນ ໄຟລ໌ redirects.txt.
ພວກເຮົາໃຊ້ checkdiff builder ຂອງ Rediraffe ເພື່ອຮັບປະກັນວ່າໜ້າຕ່າງໆຈະບໍ່ຖືກລຶບອອກຈາກເອກະສານໂດຍບໍ່ມີການປ່ຽນເສັ້ນທາງ. Builder ນີ້ຖືກດຳເນີນການເປັນສ່ວນໜຶ່ງຂອງສະຄິບ build.sh ໃນ repository ແລະ ເປັນສ່ວນໜຶ່ງຂອງການ build ອັດຕະໂນມັດຂອງພວກເຮົາເມື່ອທ່ານສົ່ງຄຳຮ້ອງຂໍການລວມ (Merge Request/MR).
ຕໍ່ໄປນີ້ແມ່ນບາງຕົວຢ່າງຂອງສະຖານະການທີ່ທ່ານຄວນສ້າງການປ່ຽນເສັ້ນທາງ.
You are moving systemdev/calendars.rst to appdev/calendars.rst. Add the following to the redirects.txt file:
"systemdev/calendars.txt" "appdev/calendars.txt"
You are moving appdev/clickable.rst into several pages in appdev/clickable/ to give significantly more information about the tool than there was previously. You have created an introduction page, appdev/clickable/introduction.rst. In this case, it would be a good idea to redirect the old page to the new introduction page. This can be done by adding the following to redirects.txt:
"appdev/clickable.rst" "appdev/clickable/introduction.rst"
ຄຳເຕືອນ¶
ການແກ້ໄຂຂອງທ່ານຕ້ອງບໍ່ນຳສະເໜີຄຳເຕືອນໃດໆເຂົ້າໃນການ build ເອກະສານ. ຖ້າມີຄຳເຕືອນເກີດຂຶ້ນ, ການ build ຈະລົ້ມເຫຼວ ແລະ ຄຳຮ້ອງຂໍການລວມຈະຖືກໝາຍດ້ວຍ 'X' ສີແດງ. ກະລຸນາຮັບປະກັນວ່າ RST ຂອງທ່ານຖືກຕ້ອງກ່ອນທີ່ທ່ານຈະສ້າງຄຳຮ້ອງຂໍການລວມ. ສິ່ງນີ້ຖືກເຮັດໂດຍອັດຕະໂນມັດ (ຜ່ານ sphinx-build crashing ກັບຄວາມຜິດພາດຂອງທ່ານ) ຖ້າທ່ານປະຕິບັດຕາມ ຄຳແນະນຳການ build ຂອງພວກເຮົາ ຂ້າງລຸ່ມນີ້.
ຄວາມຍາວຂອງແຖວ¶
ບໍ່ມີຂໍ້ຈຳກັດກ່ຽວກັບຄວາມຍາວຂອງແຖວໃນ repository ນີ້. ກະລຸນາຢ່າຕັດແຖວຕາມຄວາມຍາວທີ່ກຳນົດເອງ. ແທນທີ່ຈະເປັນແນວນັ້ນ, ໃຫ້ເປີດໃຊ້ການຕັດຄຳ (word wrap) ໃນຕົວແກ້ໄຂຂໍ້ຄວາມຂອງທ່ານ.
ຂັ້ນຕອນການປະກອບສ່ວນ¶
ຂັ້ນຕອນຕໍ່ໄປນີ້ອະທິບາຍວິທີທີ່ທ່ານສາມາດປະກອບສ່ວນເຂົ້າໃນເອກະສານນີ້.
Note
ທ່ານຈະຕ້ອງການບັນຊີ GitLab ເພື່ອເຮັດສຳເລັດຂັ້ນຕອນເຫຼົ່ານີ້. ຖ້າທ່ານບໍ່ມີບັນຊີ, ໄປທີ່ gitlab.com ເພື່ອສ້າງບັນຊີ.
ການ Fork repository¶
ທ່ານສາມາດເຮັດການແກ້ໄຂຂັ້ນສູງຕໍ່ເອກະສານໂດຍການ fork ubports/docs.ubports.com ໃນ GitLab.
ການສ້າງ (Building) ເອກະສານ¶
ເພື່ອສ້າງເອກະສານນີ້, ໃຫ້ປະຕິບັດຕາມຄຳແນະນຳເຫຼົ່ານີ້ໃນ local copy ຂອງ fork repository ຂອງທ່ານ.
ເອກະສານສາມາດຖືກສ້າງຂຶ້ນໂດຍການແລ່ນ ./build.sh ໃນ root ຂອງ repository ນີ້. ສະຄິບຍັງຈະສ້າງສະພາບແວດລ້ອມການ build ແບບ virtual ໃນ ~/ubportsdocsenv ຖ້າບໍ່ມີ.
ຖ້າທຸກຢ່າງເປັນໄປດ້ວຍດີ, ທ່ານສາມາດເຂົ້າໄປໃນໄດເຣັກທໍຣີ _build/html ແລະ ເປີດ index.html ເພື່ອເບິ່ງເອກະສານ UBports.
ຖ້າທ່ານມີບັນຫາໃນການສ້າງເອກະສານ, ສິ່ງທຳອິດທີ່ຄວນລອງຄືລຶບສະພາບແວດລ້ອມການ build. ແລ່ນ rm -r ~/ubportsdocsenv ແລະ ລອງ build ອີກຄັ້ງ.
ການກວດສອບຄັ້ງສຸດທ້າຍຂອງການປະກອບສ່ວນຂອງທ່ານ¶
ຫຼັງຈາກທ່ານໄດ້ສ້າງ Merge Request ໃນ GitLab, ລະບົບ Continuous Integration (CI) ຈະເຮັດການ test build ສຳລັບການປະກອບສ່ວນຂອງທ່ານ ("pipeline"). ກະລຸນາກວດສອບອີກຄັ້ງວ່າສິ່ງນີ້ build ສຳເລັດຫຼືບໍ່ ແລະ ຜົນໄດ້ຮັບເບິ່ງຄືກັບທີ່ທ່ານຕັ້ງໃຈໄວ້ຫຼືບໍ່:
ຢູ່ເທິງສຸດຂອງແຖບ "Overview" ຂອງ MR ຂອງທ່ານໃນ gitlab ທ່ານຈະເຫັນສະຖານະຂອງ pipeline
ຖ້າມັນເວົ້າວ່າ "Checking pipeline status" ຫຼື "Pipeline running" ກະລຸນາລໍຖ້າອີກນາທີ.
ຖ້າມັນເວົ້າວ່າ "Pipeline failed" ພ້ອມກັບ X ສີແດງ, ສະແດງວ່າມີບາງຢ່າງຜິດພາດ, ກະລຸນາຄິກທີ່ລິ້ງເພື່ອຊອກຫາລາຍລະອຽດ
ຖ້າມັນເວົ້າວ່າ "Pipeline passed" ພ້ອມກັບເຄື່ອງໝາຍຖືກສີຂຽວ, ມັນໝາຍຄວາມວ່າ MR ສາມາດຖືກ build ສຳເລັດ ແລະ ທ່ານສາມາດດຳເນີນການເບິ່ງຜົນໄດ້ຮັບ
ຕອນນີ້ກະລຸນາຄິກທີ່ລິ້ງຂອງ pipeline ນັ້ນ
ຄິກທີ່ job "build"
ສິ່ງນີ້ຈະນຳທ່ານໄປສູ່ຕອນທ້າຍຂອງບັນທຶກ build, ບ່ອນທີ່ທ່ານຈະເຫັນຂໍ້ຄວາມ: "Build succeeded, browse the artifact here"
ຄິກທີ່ລິ້ງຂ້າງໆມັນເພື່ອເບິ່ງເວັບໄຊທ໌ເອກະສານ UBports ສະບັບເຕັມທີ່ມີການປ່ຽນແປງຂອງທ່ານ
ກວດສອບອີກຄັ້ງວ່າການປ່ຽນແປງຂອງທ່ານເບິ່ງຄືວ່າ ok ຫຼືບໍ່
ວິທີການທາງເລືອກໃນການປະກອບສ່ວນ¶
ການແປພາສາ¶
ທ່ານສາມາດຊອກຫາອົງປະກອບຂອງເອກະສານນີ້ເພື່ອແປໄດ້ທີ່ ໂຄງການຂອງມັນໃນ UBports Weblate.
ການຂຽນເອກະສານທີ່ບໍ່ຢູ່ໃນຮູບແບບ RST¶
ຖ້າທ່ານຕ້ອງການຂຽນເອກະສານສຳລັບ UBports ແຕ່ບໍ່ສະດວກໃນການຂຽນ ReStructuredText, ກະລຸນາຂຽນມັນໂດຍບໍ່ມີການຈັດຮູບແບບ ແລະ ໂພສລົງໃນ UBports Forum ໃນພາກສ່ວນທີ່ກ່ຽວຂ້ອງ (ໜ້າຈະເປັນ General). ບາງຄົນຈະສາມາດຊ່ວຍທ່ານແກ້ໄຂຮ່າງຂອງທ່ານ ແລະ ຂຽນ ReStructuredText ທີ່ຕ້ອງການ.
ບໍ່ສະດວກກັບ Git¶
ຖ້າທ່ານໄດ້ຂຽນເອກະສານທີ່ສົມບູນໃນ ReStructuredText ແຕ່ບໍ່ສະດວກໃນການໃຊ້ Git ຫຼື GitLab, ກະລຸນາໂພສລົງໃນ UBports Forum ໃນພາກສ່ວນທີ່ກ່ຽວຂ້ອງ (ໜ້າຈະເປັນ General). ບາງຄົນຈະສາມາດຊ່ວຍທ່ານແກ້ໄຂຮ່າງຂອງທ່ານ ແລະ ສົ່ງມັນເຂົ້າໃນເອກະສານນີ້.
TODOs ປັດຈຸບັນ¶
ພາກສ່ວນນີ້ລາຍຊື່ TODOs ທີ່ໄດ້ຖືກລວມເຂົ້າໃນເອກະສານນີ້. ຖ້າທ່ານຮູ້ວິທີແກ້ໄຂອັນໃດອັນໜຶ່ງ, ກະລຸນາສົ່ງ merge request ໃຫ້ພວກເຮົາເພື່ອເຮັດໃຫ້ມັນດີຂຶ້ນ!
To create a todo, add this markup to your page:
.. todo::
My todo text
ສິ່ງທີ່ຕ້ອງເຮັດ (Todo)
There is also another way to create somewhat more featureful webapps, sometimes referred to as webapp+ or alternative container. This needst to be properly documented. It's a simple qml app that can be easily configured. Creation is almost as simple as 'classic' webapp, but result is more powerfull with the a nice navigation feature. A rather advanced example of this is the YouTube app from Mateo Salta which has quite some modifications on top of the template.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-lo/checkouts/latest/appdev/webapp/index.rst, line 19.)
ສິ່ງທີ່ຕ້ອງເຮັດ (Todo)
ພິຈາລະນາຂຽນເອກະສານກ່ຽວກັບຂະບວນການຈັດການກັບ merge requests ດ້ວຍ.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-lo/checkouts/latest/about/process/issue-tracking.rst, line 36.)
ສິ່ງທີ່ຕ້ອງເຮັດ (Todo)
ບັນທຶກຂະບວນການສຳລັບ Nexus 4 (mako)
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-lo/checkouts/latest/systemdev/kernel-hal.rst, line 57.)
ການໂຮດຕິ້ງ ReadTheDocs¶
ເວັບໄຊທ໌ເອກະສານ ຕົວຈິງຖືກສ້າງຂຶ້ນ ແລະ ໂຮດໃຫ້ພວກເຮົາໂດຍໂຄງການ Read The Docs. ການຕັ້ງຄ່າ RTD ຂອງພວກເຮົາປະກອບມີໂຄງການຫຼັກໜຶ່ງສຳລັບພາສາອັງກິດ ແລະ ໂຄງການເພີ່ມເຕີມໜຶ່ງສຳລັບແຕ່ລະພາສາທີ່ຮອງຮັບທີ່ເພີ່ມເປັນການແປພາສາໃຫ້ກັບໂຄງການຫຼັກ. ຖ້າທ່ານເປັນຜູ້ບຳລຸງຮັກສາ (maintainer) ແລະ ຕ້ອງການເພີ່ມພາສາ, ກ່ອນອື່ນໝົດໃຫ້ສ້າງໂຄງການໃໝ່ດ້ວຍການນຳເຂົ້າດ້ວຍຕົນເອງ ແລະ ຕັ້ງຄ່າພາສາໃຫ້ເໝາະສົມ. ຫຼັງຈາກນັ້ນເພີ່ມສິ່ງນີ້ເປັນການແປພາສາໃນໜ້າ Admin ຂອງໂຄງການຫຼັກ.