கட்டுமான ஆவணங்கள்

BeeWare Docs Tools-இன் ஆவணத்தில் ஏதேனும் மாற்றங்களைச் செய்வதற்கு முன், ஏற்கனவே உள்ள ஆவணத்தை உங்களால் உருவாக்க முடியும் என்பதை உறுதி செய்வது உதவியாக இருக்கும்.

நீங்கள் ஆவணத்தை உருவாக்குவதற்கும், ஒரு மேம்பாட்டுச் சூழலை அமைப்பதற்கும் முன்.

உங்கள் path-இல் ஒரு Python 3.13 இன்டர்ப்ரெட்டர் நிறுவப்பட்டு, கிடைக்கப்பெற வேண்டும் (அதாவது, python3.13 ஒரு Python 3.13 இன்டர்ப்ரெட்டரைத் தொடங்க வேண்டும்).

BeeWare Docs Tools ஆவணங்களை உருவாக்க tox-ஐப் பயன்படுத்துகிறது. பின்வரும் tox கட்டளைகள், tox.ini கோப்பு உள்ள அதே இடத்திலிருந்து இயக்கப்பட வேண்டும், அது திட்டத்தின் ரூட் டைரக்டரியில் உள்ளது.

நேரடி ஆவண முன்னோட்டம்

ஆவணங்களை விரைவாகத் திருத்த உதவுவதற்காக, BeeWare Docs Tools ஒரு "நேரடி முன்னோட்டம்" பயன்முறையைக் கொண்டுள்ளது.

நேரடி முன்னோட்டம் எச்சரிக்கைகளுடன் உருவாக்கப்படும்!

உங்கள் ஆவணப் புதுப்பிப்புகளைச் சோதித்துப் பார்க்க நேரலை சேவையகம் கிடைக்கிறது. நீங்கள் புதுப்பிப்புகளைச் செய்யும் போது, ஒரு குறியீட்டுப் பிழையை ஏற்படுத்தக்கூடும். WARNING எனக் கருதப்படும் சிக்கல்கள் ஒரு சாதாரண பில்டைத் தோல்வியடையச் செய்யும், இருப்பினும், லைவ் சர்வர் பில்டிங்கைத் தொடரும் அதே வேளையில், கன்சோல் வெளியீட்டில் எச்சரிக்கைகளைக் காட்டும்படி அமைக்கப்பட்டுள்ளது. இது லைவ் ப்ரீவியூவை மீண்டும் தொடங்க வேண்டிய அவசியமின்றி, உங்கள் மாற்றங்களைத் திரும்பச் செய்ய அனுமதிக்கிறது.

ஒரு WARNING என்பது மற்றொரு ERROR-இலிருந்து வேறுபட்டது. நீங்கள் ERROR எனக் கருதப்படும் ஒரு சிக்கலை அறிமுகப்படுத்தினால், லைவ் சர்வர் செயலிழந்து, மீண்டும் தொடங்குவதற்குத் தேவைப்படும். ERROR சிக்கல் தீர்க்கப்படும் வரை அது மீண்டும் தொடங்காது.

நேரலை சேவையகத்தைத் தொடங்க:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

இது ஆவணங்களை உருவாக்கி, ஆவணங்களை வழங்க ஒரு வலை சேவையகத்தைத் தொடங்கி, ஆவணங்களின் மூலக் கோப்புகளில் ஏதேனும் மாற்றங்கள் ஏற்படுகிறதா என கோப்பு அமைப்பைக் கண்காணிக்கும்.

சர்வர் துவக்கப்பட்டவுடன், கன்சோல் வெளியீட்டில் பின்வருவன போன்ற ஒன்றை நீங்கள் காண்பீர்கள்:

தகவல் - [11:18:51] http://127.0.0.1:8000/ இல் சேவை செய்கிறது

ஒரு உலாவியைத் திறந்து, வழங்கப்பட்ட URL-க்குச் செல்லவும். இப்போது நீங்கள் ஆவணத்தில் திருத்தங்களைச் செய்யத் தொடங்கலாம். ஒரு மாற்றம் கண்டறியப்பட்டால், ஆவணம் மீண்டும் உருவாக்கப்படும், மேலும் மாற்றியமைக்கப்பட்ட பக்கத்தைப் பார்க்கும் எந்தவொரு உலாவியும் தானாகவே புதுப்பிக்கப்படும்.

docs-live ஒரு ஆரம்பப் படியாகும்.

நேரலை சேவையகத்துடன் வேலை செய்ய docs-live இயக்குவது ஆரம்பகட்ட மறுஆய்வுக்கு மட்டுமே. ஒரு புல் கோரிக்கையைச் சமர்ப்பிக்கும் முன், நீங்கள் எப்போதும் ஒரு உள்ளூர் உருவாக்கத்தை இயக்க வேண்டும்.

உள்ளூர் உருவாக்கம்

நீங்கள் மீண்டும் மீண்டும் மேம்படுத்துவதை முடித்தவுடன், ஆவணங்களுக்கான உள்ளூர் கட்டமைப்பைச் செய்ய வேண்டும். ஏதேனும் குறியீட்டுப் பிழைகள் இருந்தால், இந்தக் கட்டமைப்புத் செயல்முறை தோல்வியடையும் வகையில் வடிவமைக்கப்பட்டுள்ளது. இது, நேரலை சேவையகத்தில் நீங்கள் தவறவிட்டிருக்கக்கூடிய எதையும் கண்டறிய உதவுகிறது.

உள்ளூர் உருவாக்கத்தை உருவாக்குதல்

உள்ளூர் பில்டை உருவாக்க:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

இந்த பில்டின் வெளியீடு, ப்ராஜெக்ட்டின் ரூட் கோப்பகத்தில் உள்ள _build கோப்பகத்தில் இருக்கும்.

உள்ளூர் மொழிபெயர்க்கப்பட்ட பில்டை உருவாக்குதல்

BeeWare Docs Toolsயின் ஆவணங்கள் பல மொழிகளில் மொழிபெயர்க்கப்பட்டுள்ளன. ஆங்கில ஆவணங்களில் செய்யப்படும் புதுப்பிப்புகள், மற்ற மொழி பில்ட்களில் சிக்கல்களை ஏற்படுத்தக்கூடும். ஒரு புல் கோரிக்கையைச் சமர்ப்பிக்கும் முன், அனைத்து பில்ட்களும் சரியாக வேலை செய்கின்றனவா என்பதைச் சரிபார்ப்பது அவசியம்.

கிடைக்கக்கூடிய அனைத்து மொழிபெயர்ப்புகளின் பில்டை உருவாக்க:

macOSLinuxWindows

(வினைச்சொல்) $ tox -e docs-all

(வினைச்சொல்) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

ஒவ்வொரு மொழி உருவாக்கத்தின் வெளியீடும் அதனுடன் தொடர்புடைய _build/html/<languagecode> கோப்பகத்தில் இருக்கும், இதில் <languagecode> என்பது அந்தந்த மொழியுடன் தொடர்புடைய இரண்டு அல்லது ஐந்து எழுத்துக்கள் கொண்ட மொழி குறியீடாகும் (எ.கா. பிரெஞ்சு மொழிக்கு fr, இத்தாலிய மொழிக்கு it, போன்றவை).

ஒரு தனிப்பட்ட பில்டில் உங்களுக்கு ஒரு சிக்கல் ஏற்பட்டால், tox -e docs-<languagecode> என்பதை இயக்கி அந்தந்த பில்டைத் தனித்தனியாக இயக்கலாம். உதாரணமாக, பிரெஞ்சு ஆவணங்களை மட்டும் உருவாக்க, பின்வருமாறு இயக்கவும்:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

ஒரு மொழிக்கான பில்டின் வெளியீடு _build கோப்பகத்தில் இருக்கும்.

ஆவணப்படுத்தல் லிண்டிங்

கட்டமைப்பு செயல்முறை மார்க்அப் பிழைகளைக் கண்டறியும், ஆனால் BeeWare Docs Tools என்பது "லிண்டிங்" எனப்படும் பாணி மற்றும் வடிவமைப்புக்கான சில கூடுதல் சோதனைகளைச் செய்கிறது. லிண்ட் சோதனைகளை இயக்க:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

இது ஆவணத்தில் பின்வருவன அடங்கவில்லை என்பதைச் சரிபார்க்கும்:

• செயலிழந்த இணைப்புகள்
• தவறாக எழுதப்பட்ட வார்த்தைகள்

ஒரு வார்த்தையின் சரியான எழுத்துப்பிழை, தவறாக எழுதப்பட்டதாகக் கண்டறியப்பட்டால், அந்த வார்த்தையை docs/spelling_wordlist என்பதில் உள்ள பட்டியலில் சேர்க்கவும். இது அந்த வார்த்தையை எழுத்துப்பிழை சரிபார்ப்பாளரின் அகராதியில் சேர்க்கும். இந்தப் பட்டியலில் சேர்க்கும்போது, நினைவில் கொள்ளுங்கள்:

• நாங்கள் அமெரிக்க எழுத்துப்பிடியை விரும்புகிறோம், மேலும் நிரலாக்கத்திற்கே உரிய சில பேச்சு வழக்குகளுக்கும் (எ.கா., "apps") பெயர்களைச் செயலாக்குவதற்கும் (எ.கா., "scrollable") சில சுதந்திரங்கள் எடுத்துக்கொள்கிறோம்.
• ஒரு தயாரிப்புப் பெயரைக் குறிப்பிடும்போது, அந்தத் தயாரிப்பின் விரும்பப்படும் பெரியெழுத்துப் பயன்பாட்டைப் பயன்படுத்த வேண்டும். (எ.கா., "macOS", "GTK", "pytest", "Pygame", "PyScript").
• ஒரு சொல் "குறியீடாக" பயன்படுத்தப்பட்டால், அதை அகராதியில் சேர்ப்பதற்குப் பதிலாக, ஒரு நேரியல் (like this) ஆக மேற்கோள் காட்ட வேண்டும்.

நீங்கள் ஆவணங்களை வெற்றிகரமாக உருவாக்கியவுடன், ஆவணங்களை எழுத நீங்கள் தயாராக உள்ளீர்கள்.