உள்ளடக்கத்திற்கு செல்க

ஆவணங்களைச் சேர்த்தல்

உங்களிடம் உலகின் சிறந்த மென்பொருள் இருக்கலாம் - ஆனால் அதை எப்படிப் பயன்படுத்துவது என்று யாருக்கும் தெரியாவிட்டால், அதன் பயன் என்ன? ஆவணங்களை எப்போதும் மேம்படுத்தலாம் - மேலும் உங்கள் உதவி எங்களுக்குத் தேவை!

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

BeeWare Docs Tools-இன் ஆவணப்படுத்தல் MkDocs மற்றும் Markdown பயன்படுத்தி எழுதப்படுகிறது. ஆவணப்படுத்தலை கட்டமைக்க Diataxis கட்டமைப்பைப் பின்பற்ற நாங்கள் இலக்கு வைத்துள்ளோம்.

டயடாக்சிஸ் கட்டமைப்பு நான்கு வகையான ஆவணங்களை விவரிக்கிறது:

  • கற்பித்தல் - ஒரு குறிப்பிட்ட திட்ட இலக்கைக் கொண்ட, வழிகாட்டப்பட்ட கற்றல் அனுபவம்.
  • செய்முறை வழிகாட்டி - வாசகரை ஒரு குறிப்பிட்ட இலக்கு அல்லது விளைவை நோக்கி வழிநடத்தும் வழிமுறைகள்.
  • தலைப்பு வழிகாட்டி - ஒரு தனிப்பட்ட கருத்தை, அதன் அடிப்படைக் கருத்துக்கள் தெளிவாக விளங்கும் வகையில் விவாதிப்பது.
  • குறிப்பு - குறிப்பிட்ட ஏபிஐ-கள் அல்லது பிற இடைமுகங்களின் தொழில்நுட்ப விளக்கங்கள்.

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

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

கற்பனை

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

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

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

செய்முறை வழிகாட்டி

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

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

தலைப்பு வழிகாட்டி

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

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

மேற்கோள்

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

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

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

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

ஆவணங்களைப் பங்களித்தல்

புதிய ஆவணப்படுத்தலை முன்மொழிதல்

புதிய அம்சத்தை முன்மொழிதல்

எனவே, BeeWare Docs Tools மேம்பாடு குறித்த ஒரு யோசனை உங்களிடம் உள்ளது - அதை பரிசீலனைக்கு எவ்வாறு சமர்ப்பிப்பது?

உங்கள் ஆராய்ச்சியைச் செய்யுங்கள்

முதல் படி, ஏற்கனவே உள்ள [அம்சச் சிக்கல்களைக் (அம்ச மேம்பாடு எனக் குறியிடப்பட்ட சிக்கல்கள்)]BeeWare Docs Tools கண்டறிய (https://github.com/beeware/beeware-docs-tools/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement) சிக்கல் கண்காணிப்பான் தேடுவதாகும், தகவல் ஆவணப் பிரச்சினைகள் ( "documentation" எனக் குறியிடப்பட்ட பிரச்சினைகள்), அல்லது கலந்துரையாடல் இழைகள் ஆகியவற்றைப் பார்த்து, அந்த யோசனை முன்பே பரிந்துரைக்கப்பட்டதா எனப் பார்க்கவும். அப்படி இருந்தால், மேலும் நீங்கள் சேர்க்க புதிய சூழல் அல்லது யோசனைகள் இருந்தால், அவற்றை ஏற்கனவே உள்ள உரையாடலில் சேர்க்கவும். உங்கள் ஆராய்ச்சிக்கு உதவி தேவைப்பட்டால், BeeWare Discord-இல் உள்ள #dev சேனலில் கேட்கலாம். ஏற்கனவே உள்ள உரையாடல் இழைகளைக் கண்டறிந்து காட்ட, உங்களுக்குத் தெரியாத பின்னணியை வழங்க, அல்லது உடனடியாகத் தொடர்புடையதாகத் தோன்றாத மற்றொரு யோசனையுடன் உங்கள் யோசனையை இணைக்க நாங்கள் உதவக்கூடும்.

கருத்தை விவாதிக்கவும்

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

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

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

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

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

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

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

ஒரு முறையான அம்சக் கோரிக்கையாக மாற்றுக

ஒரு அம்சத்தின் வடிவத்தைப் பற்றி விவாதம் ஒருமித்த கருத்தை அடைந்தவுடன், விவாதத்தின் சுருக்கத்தை அளித்து, சூழலுக்காக விவாதத்திற்கான இணைப்பைச் சேர்த்து, beeware-docs-tools சிக்கல் கண்காணிப்பான்-இல் ஒரு புதிய அம்சக் கோரிக்கை சிக்கலை உருவாக்கலாம்.

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

உங்களுக்கு ஆர்வமிருந்தால், நீங்கள் உங்கள் புதிய அம்சத்தைச் செயல்படுத்தத் தொடங்கலாம்.

ஒரு மேம்பாட்டுச் சூழலை அமைக்கவும்

ஒரு மேம்பாட்டுச் சூழலை அமைத்தல்

BeeWare Docs Tools-க்கு பங்களிப்பதற்கு, நீங்கள் ஒரு மேம்பாட்டுச் சூழலை அமைக்க வேண்டும்.

முன்நிபந்தனைகள்

பின்வரும் முன்நிபந்தனைகளை நீங்கள் நிறுவ வேண்டும்.

BeeWare Docs Tools க்கு Python 3.10+ தேவை. மெய்நிகர் சூழல்களை நிர்வகிப்பதற்கான ஒரு முறையையும் (எ.கா. venv) நீங்கள் பயன்படுத்த வேண்டும்.

பின்வருவதை இயக்கி, நீங்கள் நிறுவியுள்ள பைத்தானின் பதிப்பைச் சரிபார்க்கலாம்:

பைத்தான் 3.8.10

நீங்கள் பைத்தனின் ஒன்றுக்கு மேற்பட்ட பதிப்புகளை நிறுவியிருந்தால், நீங்கள் python3 என்பதை ஒரு குறிப்பிட்ட பதிப்பு எண்ணுடன் (எ.கா., python3.13) மாற்ற வேண்டியிருக்கலாம்.

சமீபத்தில் வெளியிடப்பட்ட பைத்தானின் பதிப்பைத் (அதாவது, ".0" அல்லது ".1" என்ற நுண் பதிப்பு எண்ணைக் கொண்ட பதிப்புகள், எ.கா., 3.14.0) தவிர்க்கப் பரிந்துரைக்கிறோம். ஏனெனில், macOS-இல் பைத்தானை ஆதரிக்கத் தேவையான கருவிகள், சமீபத்தில் வெளியிடப்பட்ட நிலையான பைத்தான் பதிப்புகளுக்குப் பொதுவாகக் கிடைப்பதில்லை அல்லது தாமதமாகக் கிடைக்கின்றன.

BeeWare Docs Tools க்கு Python 3.10+ தேவை. மெய்நிகர் சூழல்களை நிர்வகிப்பதற்கான ஒரு முறையையும் (எ.கா. venv) நீங்கள் பயன்படுத்த வேண்டும்.

பின்வருவதை இயக்கி, நீங்கள் நிறுவியுள்ள பைத்தானின் பதிப்பைச் சரிபார்க்கலாம்:

பைத்தான் 3.8.10

நீங்கள் பைத்தனின் ஒன்றுக்கு மேற்பட்ட பதிப்புகளை நிறுவியிருந்தால், நீங்கள் python3 என்பதை ஒரு குறிப்பிட்ட பதிப்பு எண்ணுடன் (எ.கா., python3.13) மாற்ற வேண்டியிருக்கலாம்.

சமீபத்தில் வெளியிடப்பட்ட பைத்தானின் பதிப்பைத் (அதாவது, ".0" அல்லது ".1" என்ற நுண் பதிப்பு எண்ணைக் கொண்ட பதிப்புகள், எ.கா., 3.14.0) தவிர்க்குமாறு நாங்கள் பரிந்துரைக்கிறோம். ஏனெனில், லினக்ஸில் பைத்தானை ஆதரிக்கத் தேவையான கருவிகள், சமீபத்தில் வெளியிடப்பட்ட நிலையான பைத்தான் பதிப்புகளுக்குப் பொதுவாகக் கிடைப்பதில்லை.

BeeWare Docs Tools க்கு Python 3.10+ தேவை. மெய்நிகர் சூழல்களை நிர்வகிப்பதற்கான ஒரு முறையையும் (எ.கா. venv) நீங்கள் பயன்படுத்த வேண்டும்.

பின்வருவதை இயக்கி, நீங்கள் நிறுவியுள்ள பைத்தானின் பதிப்பைச் சரிபார்க்கலாம்:

C:\...>py -3 --version

உங்களிடம் பைத்தனின் ஒன்றுக்கு மேற்பட்ட பதிப்புகள் நிறுவப்பட்டிருந்தால், நீங்கள் -3-ஐ ஒரு குறிப்பிட்ட பதிப்பு எண்ணுடன் (எ.கா., -python3.13) மாற்ற வேண்டியிருக்கலாம்.

சமீபத்தில் வெளியிடப்பட்ட பைத்தானின் பதிப்பைத் (அதாவது, ".0" அல்லது ".1" என்ற நுண் பதிப்பு எண்ணைக் கொண்ட பதிப்புகள், எ.கா., 3.14.0) தவிர்க்குமாறு நாங்கள் பரிந்துரைக்கிறோம். ஏனெனில், விண்டோஸில் பைத்தானை ஆதரிக்கத் தேவையான கருவிகள், சமீபத்தில் வெளியிடப்பட்ட நிலையான பைத்தான் பதிப்புகளுக்குப் பொதுவாகக் கிடைப்பதில்லை அல்லது தாமதமாகக் கிடைக்கின்றன.

உங்கள் மேம்பாட்டுச் சூழலை அமைக்கவும்

BeeWare Docs Tools-க்கான உங்கள் மேம்பாட்டுச் சூழலை அமைப்பதற்கான பரிந்துரைக்கப்பட்ட வழி, ஒரு மெய்நிகர்ச் சூழலைப் பயன்படுத்தி, பின்னர் BeeWare Docs Tools-இன் மேம்பாட்டுப் பதிப்பையும் அதன் சார்புநிலைத் தொகுப்புகளையும் நிறுவுவதாகும்.

BeeWare Docs Tools களஞ்சியத்தை நகலெடுக்கவும்

அடுத்து, GitHub-இல் உள்ள BeeWare Docs Tools பக்கத்திற்குச் செல்லவும், மேலும், நீங்கள் ஏற்கனவே செய்யவில்லை என்றால், கிடங்கை உங்கள் கணக்கில் ஃபோர்க் செய்யவும். அடுத்து, உங்கள் ஃபோர்க்கில் உள்ள "<> Code" பொத்தானைக் கிளிக் செய்யவும். உங்கள் கணினியில் GitHub டெஸ்க்டாப் பயன்பாடு நிறுவப்பட்டிருந்தால், நீங்கள் "Open with GitHub Desktop" என்பதைத் தேர்ந்தெடுக்கலாம்; இல்லையெனில், வழங்கப்பட்ட HTTPS URL-ஐ நகலெடுத்து, கட்டளை வரியைப் பயன்படுத்தி உங்கள் கணினிக்கு ரெபாசிட்டரியைக் குளோன் செய்ய அதைப் பயன்படுத்தவும்:

BeeWare Docs Tools களஞ்சியத்தை ஃபோர்க் செய்து, பின்னர்:

$ git clone https://github.com/<உங்கள் பயனர் பெயர்>/beeware-docs-tools.git

(உங்கள் GitHub பயனர் பெயரை இங்கே மாற்றவும்)

BeeWare Docs Tools களஞ்சியத்தை ஃபோர்க் செய்து, பின்னர்:

$ git clone https://github.com/<உங்கள் பயனர் பெயர்>/beeware-docs-tools.git

(உங்கள் GitHub பயனர் பெயரை இங்கே மாற்றவும்)

BeeWare Docs Tools களஞ்சியத்தை ஃபோர்க் செய்து, பின்னர்:

C:\...>git clone https://github.com/<உங்கள் பயனர் பெயர்>/beeware-docs-tools.git

(உங்கள் GitHub பயனர் பெயரை இங்கே மாற்றவும்)

மேல்நிலை களஞ்சியத்தை அமைக்கவும்

உங்கள் ஃபோர்க்கை கிளோன் செய்த பிறகு, BeeWare ரெபாசிட்டரியை ஒரு upstream ரிமோட்டாகச் சேர்க்கவும். இது உங்கள் உள்ளூர் கிளோனுக்கு அசல் ரெபாசிட்டரியின் ஒரு குறிப்பை வழங்குகிறது, காலப்போக்கில் புதுப்பிப்புகளை ஒத்திசைப்பதை எளிதாக்குகிறது.

Toga மற்றும் Briefcase போன்ற கருவிகள் துல்லியமான பதிப்பு எண்களைத் தீர்க்க upstream இலிருந்து வரும் டேக்குகளும் உங்களுக்குத் தேவைப்படும்:

$ git remote add upstream https://github.com/beeware/beeware-docs-tools.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware-docs-tools.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware-docs-tools.git
C:\...>git fetch --tags upstream

உங்கள் ஃபோர்க்கிலும் அந்த டேக்குகளைச் சேர்க்க விரும்பினால், அவற்றை நீங்கள் புஷ் செய்யலாம்:

$ கிட் புஷ் --டேக்ஸ்

நீங்கள் பின்னர் ஒரு புதிய கிளைனை உருவாக்கி, உங்கள் ஃபோர்க்கிலிருந்து டேக்குகள் கிடைக்க வேண்டும் என்று விரும்பினால் இது பயனுள்ளதாக இருக்கும்.

ஒரு மெய்நிகர் சூழலை உருவாக்கவும்

மெய்நிகர் சூழலை அமைக்க மற்றும் மேம்படுத்த pip, பின்வருவனவற்றை இயக்கவும்:

$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware-docs-tools
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

உங்கள் கட்டளையின் முன்னால் இப்போது ஒரு (.venv) முன்னொட்டு இருக்க வேண்டும்.

நிறுவவும் BeeWare Docs Tools

இப்போது உங்களிடம் மூலக் குறியீடு இருப்பதால், உங்கள் மேம்பாட்டுச் சூழலில் (https://setuptools.pypa.io/en/latest/userguide/development_mode.html) ஐ ஒரு [திருத்தக்கூடிய நிறுவல்]BeeWare Docs Tools செய்யலாம். பின்வரும் கட்டளையை இயக்கவும்:

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

முன்-அர்ப்பணிப்பை இயக்கவும்

BeeWare Docs Tools எளிமையான சிக்கல்களைக் கண்டறியவும், குறியீட்டு வடிவமைப்பைத் தரப்படுத்தவும் pre-commit என்ற கருவியைப் பயன்படுத்துகிறது. எந்தவொரு git commit-ஐயும் இறுதி செய்வதற்கு முன்பு, தானாகவே தொடர்ச்சியான code linters-களை இயக்கும் ஒரு git hook-ஐ நிறுவுவதன் மூலம் இது செயல்படுகிறது. pre-commit-ஐ இயக்க, பின்வருவனவற்றை இயக்கவும்:

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

இப்போது நீங்கள் BeeWare Docs Tools ஹேக்கிங் செய்யத் தயாராக உள்ளீர்கள்!

கிளையிலிருந்து வேலை செய்யுங்கள்

உங்கள் main கிளை அல்ல, ஒரு அம்சக் கிளையிலிருந்து வேலை செய்யுங்கள்

உங்கள் மாற்றத்தில் வேலை செய்யத் தொடங்குவதற்கு முன், நீங்கள் ஒரு கிளை உருவாக்கியுள்ளீர்கள் என்பதை உறுதிப்படுத்திக் கொள்ளுங்கள். இயல்பாக, உங்கள் களஞ்சியப் பிளக்கை நீங்கள் நகலெடுக்கும்போது, உங்கள் main கிளையில் நீங்கள் சரிபார்க்கப்படுவீர்கள். இது BeeWare Docs Tools-இன் main கிளையின் நேரடி நகலாகும்.

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

உங்கள் முதன்மை கிளை (main branch) அடிப்படையிலான உங்கள் முதல் புல் கோரிக்கையை முடித்த பிறகு, அதிலிருந்து வேலை செய்வது உங்களுக்கும் கடினமாக்குகிறது. நீங்கள் இரண்டாவது புல் ரிக்வெஸ்டில் வேலை செய்ய விரும்பினால், உங்கள் இரண்டாவது பங்களிப்பை அடிப்படையாகக் கொள்ள, அப்ஸ்ட்ரீம் திட்டத்தின் பிரதான கிளைக்கான ஒரு "தூய்மையான" பிரதியை நீங்கள் வைத்திருக்க வேண்டும்; உங்கள் முதல் பங்களிப்பை உங்கள் main கிளையிலிருந்து செய்திருந்தால், அந்தத் தூய்மையான பதிப்பு இனி உங்களிடம் இருக்காது.

அதற்குப் பதிலாக, நீங்கள் உங்கள் மாற்றங்களை ஒரு ஃபீச்சர் பிராஞ்சில் செய்ய வேண்டும். நீங்கள் செய்த மாற்றத்தை அடையாளம் காண, ஒரு ஃபீச்சர் பிராஞ்ச் ஒரு எளிய பெயரைக் கொண்டிருக்கும். உதாரணமாக, நீங்கள் விண்டோஸ் 11-ல் கட்டமைப்புப் பிரச்சினைகளை ஏற்படுத்தும் ஒரு பிழையைச் சரிசெய்கிறீர்கள் என்றால், நீங்கள் ஒரு அம்சக் கிளையை fix-win11-build என உருவாக்கலாம். உங்கள் பிழை, ஏற்கனவே புகாரளிக்கப்பட்ட ஒரு குறிப்பிட்ட சிக்கலுடன் தொடர்புடையது என்றால், கிளைப் பெயரில் அந்தச் சிக்கல் எண்ணைக் குறிப்பிடுவதும் வழக்கம் (எ.கா., fix-1234).

ஒரு fix-win11-build ஃபீச்சர் பிராஞ்சை உருவாக்க, ஓட்டுங்கள்:

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build
எல்லை மீறலைத் தவிர்க்கவும்

எல்லை மீறலைத் தவிர்த்தல்

"எல்லை மீறல்" என்பது, ஒரு தனிப்பட்ட பங்களிப்பால் சரிசெய்யப்பட்ட சிக்கல்கள் அல்லது செயல்படுத்தப்பட்ட அம்சங்களின் பட்டியல், வேலை தொடங்கியபோது நோக்கமாக இருந்தது என்பதை விட கணிசமாக அதிகமாக வளரும்போது நிகழ்கிறது. நீங்கள் ஒரு எளிய சிக்கலுடன் தொடங்குகிறீர்கள்; அதனுடன் நெருங்கிய தொடர்புடைய மற்றொரு சிக்கலைக் கண்டறிந்து, அந்தத் தீர்வையும் சேர்க்க முடிவு செய்கிறீர்கள்; பின்னர் மூன்றாவது… நீங்கள் உணர்வதற்குள், டஜன் கணக்கான கோப்புகளை உள்ளடக்கி, 5 சிக்கல்களைத் தீர்த்து 3 புதிய அம்சங்களைச் சேர்க்கும் ஒரு புல் கோரிக்கையை நீங்கள் பெற்றிருப்பீர்கள்.

திட்ட வரம்பு மீறல் அனைவருக்கும் நடப்பதுண்டு. இது அனுபவமிக்க டெவலப்பர்களுக்கு நன்கு தெரிந்த ஒரு கருத்தாகும்; நாம் அனைவரும் பலமுறை இதைச் செய்திருக்கிறோம், அதனால் ஏற்படும் அனைத்துப் பிரச்சனைகளையும் அனுபவித்திருக்கிறோம்.

வளர்ச்சி எல்லை மீறலைத் தவிர்ப்பதற்கு மிகவும் நடைமுறைக்குரிய காரணங்கள் உள்ளன. ஒரு பங்களிப்பு எவ்வளவு பெரியதாகிறதோ, அதைக் கையாள்வது அவ்வளவு கடினமாகிறது. விளிம்புநிலை நிகழ்வுகள் அல்லது சாத்தியமான சிக்கல்களைக் கண்டறிவது கடினமாகிவிடும், இதன் பொருள் அந்தப் பங்களிப்பின் ஒட்டுமொத்தத் தரம் குறையக்கூடும். மதிப்பாய்வாளர் ஒன்றுக்கு மேற்பட்ட, தொடர்பில்லாத சூழல்களைக் கையாள வேண்டியிருக்கும்போது, மதிப்பாய்வுகளும் மிகவும் சவாலானதாகின்றன. ஒரு பெரிய பங்களிப்பு என்பது அதிக மதிப்பாய்வுக் கருத்துக்களைக் குறிக்கும், மேலும் ஒரு பங்களிப்பாளராக, பல மதிப்பாய்வுத் திரிகளைப் பின்தொடர்வது கடினமாகிவிடும். உங்கள் GitHub அனுபவமும் பாதிக்கப்படும் - ஒரு PR-இன் அளவு அதிகரிக்கும்போது GitHub-இன் பயனர் இடைமுகம் (UI) மெதுவாகிவிடும், அதாவது GitHub இடைமுகம் மூலம் கோப்புகளைப் பார்ப்பதும், மதிப்பாய்வுக் கருத்துக்களை இடுவதும் மிகவும் கடினமாகிவிடும்.

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

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

ஒவ்வொரு பங்களிப்பின் வரம்பைக் கட்டுப்படுத்துவது, உங்களை உள்ளடக்கி சம்பந்தப்பட்ட அனைவருக்கும் உதவுகிறது. உங்கள் மதிப்பாய்வாளர்கள், ஏன் நீங்களும் கூட, இதைப் பாராட்டுவார்கள்.

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

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

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 சிக்கல் தீர்க்கப்படும் வரை அது மீண்டும் தொடங்காது.

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

(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 இயக்குவது ஆரம்பகட்ட மறுஆய்வுக்கு மட்டுமே. ஒரு புல் கோரிக்கையைச் சமர்ப்பிக்கும் முன், நீங்கள் எப்போதும் ஒரு உள்ளூர் உருவாக்கத்தை இயக்க வேண்டும்.

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

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

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

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

(venv) $ tox -e docs

(venv) $ tox -e docs

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

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

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

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

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

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

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

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

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

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

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

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

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

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

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

(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) ஆக மேற்கோள் காட்ட வேண்டும்.

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

ஆவணங்களை எழுதுதல்

ஆவணங்களை எழுதுதல்

BeeWare Docs Tools-க்கான உங்கள் ஆவணப் பங்களிப்பை எழுதப் பின்பற்ற வேண்டிய படிகள் இவை.

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

தற்போதுள்ள ஆவணங்களைப் புதுப்பித்தல்

நீங்கள் ஏற்கனவே உள்ள ஆவணங்களைத் திருத்தினால், /docs/en கோப்பகத்தில் அந்தக் கோப்பை நீங்கள் கண்டறிய வேண்டும். கோப்பு அமைப்பு பக்க அமைப்பைப் பின்பற்றுகிறது, எனவே ஆவண URL-ஐப் பயன்படுத்தி நீங்கள் கோப்பைக் கண்டறியலாம்.

புதிய ஆவணத்தைச் சேர்த்தல்

நீங்கள் ஒரு புதிய ஆவணத்தைச் சேர்த்தால், இன்னும் சில படிகள் உள்ளன.

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

பின்னர், உங்கள் புதிய கோப்பைச் சேர்க்க docs/en/SUMMARY.md கோப்பை நீங்கள் புதுப்பிக்க வேண்டும். SUMMARY.md கோப்பு அடிப்படையில் docs/en கோப்பக அமைப்பைப் பிரதிபலிக்கும் வகையில் ஒழுங்கமைக்கப்பட்டுள்ளது, ஆனால், மிக முக்கியமாக, இது இடது பக்கப்பட்டியின் அமைப்பை நேரடியாகத் தீர்மானிக்கிறது. நீங்கள் new_doc.md-ஐச் சேர்க்க விரும்பும் பிரிவைக் கண்டறிந்தால், அங்கு ஒரு வைல்ட்கார்டு பாதை பட்டியலிடப்பட்டிருந்தால், SUMMARY.md-இல் எதையும் மாற்றத் தேவையில்லை. எடுத்துக்காட்டாக:

- கோப்பகப் பாதை/*

நீங்கள் new_doc.md-ஐச் சேர்க்க விரும்பும் பகுதி தனிப்பட்ட மார்க்அப் இணைப்புகளின் பட்டியலாக இருந்தால், உங்கள் இணைப்பிற்கு ஒரு வெளிப்படையான இணைப்பைச் சேர்க்க வேண்டும். உதாரணமாக:

- [எனது புதிய ஆவணம்](new_doc.md)

உங்கள் ஆவணங்களை எழுதுதல்

நீங்கள் இப்போது விரும்பிய கோப்பை உங்கள் எடிட்டரில் திறந்து, எழுதத் தொடங்கலாம்.

BeeWare-க்கான ஆவணங்களை எழுதுவதற்கான எங்கள் வழிகாட்டுதல்களை விவரிக்கும் ஒரு ஆவணப்படுத்தல் பாணி வழிகாட்டி எங்களிடம் உள்ளது.

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

மாற்றக் குறிப்பைச் சேர்க்கவும்

வெளியீட்டுக் குறிப்புகளுக்கான மாற்றத் தகவலைச் சேர்த்தல்

BeeWare Docs Tools ஒவ்வொரு வெளியீட்டிற்கான வெளியீட்டுக் குறிப்புகளை உருவாக்க உதவுவதற்காக towncrier ஐப் பயன்படுத்துகிறது. நீங்கள் ஒரு புல் ரிக்குவெஸ்டைச் சமர்ப்பிக்கும்போது, அதில் ஒரு மாற்றக் குறிப்பு இருக்க வேண்டும் - இந்த மாற்றக் குறிப்பு, செய்யப்பட்ட மாற்றத்தை விவரிக்கும் வெளியீட்டுக் குறிப்புகளில் உள்ள ஒரு பதிவாக மாறும்.

ஒவ்வொரு புல் கோரிக்கையிலும், அந்தப் புல் கோரிக்கையால் செயல்படுத்தப்பட்ட மாற்றத்தைப் பற்றிய ஒரு சுருக்கமான விளக்கத்தை வழங்கும் changes/ கோப்பகத்தில் குறைந்தது ஒரு கோப்பாவது இருக்க வேண்டும். மாற்றக் குறிப்பு, <id>.<fragment type>.md என்ற வடிவத்தில் உள்ள ஒரு கோப்பில் மார்க்அப் வடிவத்தில் இருக்க வேண்டும். நீங்கள் முன்மொழிகின்ற மாற்றம், ஏற்கனவே ஒரு சிக்கல் எண் உள்ள பிழைத்திருத்தமாக இருந்தாலோ அல்லது ஒரு அம்சமாக இருந்தாலோ, அந்த சிக்கலின் எண்ணே ஐடியாக இருக்கும். மாற்றத்திற்கு தொடர்புடைய சிக்கல் எதுவும் இல்லையென்றால், PR எண்ணை ஐடியாகப் பயன்படுத்தலாம். பல் ரிக்வெஸ்டை நீங்கள் புஷ் செய்யும் வரை இந்த PR எண்ணை உங்களால் அறிய முடியாது, எனவே முதல் CI பாஸ் towncrier சோதனையில் தோல்வியடையும்; மாற்றக் குறிப்பைச் சேர்த்து ஒரு PR புதுப்பிப்பை புஷ் செய்யவும், அதன் பிறகு CI பாஸ் ஆகும்.

ஐந்து துண்டு வகைகள் உள்ளன:

  • feature: PR ஆனது, முன்பு சாத்தியமில்லாத ஒரு புதிய நடத்தை அல்லது திறனைச் சேர்க்கிறது (எ.கா., ஒரு புதிய பேக்கேஜிங் வடிவத்திற்கு ஆதரவைச் சேர்ப்பது, அல்லது ஏற்கனவே உள்ள பேக்கேஜிங் வடிவத்தில் ஒரு புதிய அம்சத்தைச் சேர்ப்பது);
  • bugfix: PR ஆனது தற்போதைய செயலாக்கத்தில் உள்ள ஒரு பிழையை சரிசெய்கிறது;
  • doc: PR ஆவணப்படுத்தலில் ஒரு குறிப்பிடத்தக்க முன்னேற்றம்;
  • removal; PR ஆனது BeeWare Docs Tools API-இல் பின்னோக்கி இணக்கமற்ற மாற்றத்தைக் குறிக்கிறது; அல்லது
  • misc; ஒரு சிறிய அல்லது நிர்வாக மாற்றம் (எ.கா., எழுத்துப்பிழை திருத்துதல், ஒரு சிறிய மொழி விளக்கம், அல்லது ஒரு சார்பு பதிப்பைப் புதுப்பித்தல்), இது வெளியீட்டுக் குறிப்புகளில் அறிவிக்கப்பட வேண்டிய அவசியமில்லை.

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

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

எண்களில் தொடங்கும் திட்டப் பெயர்களைத் தடுக்க, வலுவான ரெகுலர் எக்ஸ்பிரஷன் சோதனையைப் பயன்படுத்தவும்.

அதற்குரிய மாற்றக் குறிப்பு ஏறக்குறைய இவ்வாறு இருக்கும்:

திட்டப் பெயர்கள் இனி எண் கொண்டு தொடங்க முடியாது.

சில PR-கள் பல அம்சங்களை அறிமுகப்படுத்தும், பல பிழைகளை சரிசெய்யும், அல்லது பல பின்னோக்கிய இணக்கமற்ற மாற்றங்களை அறிமுகப்படுத்தும். அப்படியானால், அந்த PR-ல் பல மாற்றக் குறிப்பு கோப்புகள் இருக்கலாம். இரண்டு ஃபிராக்மென்ட் வகைகளை ஒரே ஐடி-யுடன் தொடர்புபடுத்த வேண்டியிருந்தால், நீங்கள் ஒரு எண் சார்ந்த பின்னொட்டைச் சேர்க்கலாம். உதாரணமாக, PR 789, டிக்கெட் 123-ல் விவரிக்கப்பட்ட ஒரு அம்சத்தைச் சேர்த்து, டிக்கெட் 234-ல் விவரிக்கப்பட்ட ஒரு பிழையை சரிசெய்து, மேலும் இரண்டு பின்னோக்கி இணக்கமற்ற மாற்றங்களையும் செய்திருந்தால், உங்களிடம் 4 மாற்றக் குறிப்புக் கோப்புகள் இருக்கலாம்:

  • 123.feature.md
  • 234.bugfix.md
  • 789.removal.1.md
  • 789.removal.2.md

towncrier மற்றும் துண்டு வகைகள் பற்றிய கூடுதல் தகவல்களுக்கு News Fragments-ஐப் பார்க்கவும். changes களஞ்சியத்தின் BeeWare Docs Tools கோப்பகத்தில் உள்ள செய்தித் துண்டுகளின் தற்போதைய எடுத்துக்காட்டுகளையும் நீங்கள் காணலாம். இந்த கோப்புறை காலியாக இருந்தால், BeeWare Docs Tools சமீபத்தில் ஒரு புதிய வெளியீட்டை வெளியிட்டிருக்கலாம்; ஒவ்வொரு வெளியீட்டுடனும் வெளியீட்டுக் குறிப்புகளை புதுப்பிக்க, மாற்றக் குறிப்புக் கோப்புகள் நீக்கப்பட்டு இணைக்கப்படுகின்றன. தேவையான கருத்துருப் பாணியைக் காண அந்தக் கோப்பைப் பார்க்கலாம்; உங்கள் மாற்றக் குறிப்புகளை எவ்வாறு வடிவமைப்பது என்பதைக் காண சமீபத்தில் ஒன்றிணைக்கப்பட்ட PR-களை பார்க்கலாம்.

பல் ரிக்வெஸ்டைச் சமர்ப்பிக்கவும்

புல் ரிக்வெஸ்டைச் சமர்ப்பித்தல்

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

முன்-அர்ப்பணிப்புடன் பணியாற்றுதல்

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

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

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

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

எல்லாம் முடிந்ததும், கமிட் இறுதி செய்யப்பட்டது என்பதைக் குறிக்கும் ஒரு செய்தியைக் காண்பீர்கள், மேலும் உங்கள் git log-ல் உங்கள் கமிட் மிகச் சமீபத்திய சேர்ப்பாகக் காண்பிக்கப்படும். இப்போது நீங்கள் GitHub-க்கு புஷ் செய்யத் தயாராக உள்ளீர்கள்.

உங்கள் மாற்றங்களை GitHub-க்கு அனுப்பி, உங்கள் புல் கோரிக்கையை உருவாக்குங்கள்.

நீங்கள் GitHub-க்கு முதல் முறையாக புஷ் செய்யும்போது, ஒரு URL வழங்கப்படும், அது உங்களை நேரடியாக ஒரு புதிய புல் கோரிக்கையை உருவாக்க GitHub பக்கத்திற்கு அழைத்துச் செல்லும். அந்த URL-ஐப் பின்பற்றி உங்கள் புல் கோரிக்கையை உருவாக்கவும்.

பின்வருவது, URL முன்னிலைப்படுத்தப்பட்ட நிலையில், push-இல் நீங்கள் எதிர்பார்க்கக்கூடிய ஒன்றின் உதாரணத்தைக் காட்டுகிறது.

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.git
 * [new branch]      fix-win11-build -> fix-win11-build

நீங்கள் ஏற்கனவே தற்போதைய கிளை (current branch)-ஐ GitHub-க்குத் தள்ளியிருந்தால், நீங்கள் URL-ஐ மீண்டும் பெறமாட்டீர்கள். இருப்பினும், PR உருவாக்கும் URL-ஐப் பெறுவதற்கு வேறு வழிகளும் உள்ளன:

  • அப்ஸ்ட்ரீம் ரெபாசிட்டரிக்குச் சென்று, "புல் கோரிக்கைகள்" என்பதைக் கிளிக் செய்து, அதைத் தொடர்ந்து "புதிய புல் கோரிக்கை" என்பதைக் கிளிக் செய்யவும். பின்னர், உங்கள் புல் கோரிக்கையை நீங்கள் சமர்ப்பிக்க விரும்பும் இடத்திலிருந்து தேர்ந்தெடுக்கவும்.
  • நீங்கள் சமீபத்தில் புஷ் செய்திருந்தால், அப்ஸ்ட்ரீம் ரெபாசிட்டரிக்குச் சென்று, கோப்புகளின் பட்டியலுக்கு மேலே உள்ள, ரெப்போவில் "சமீபத்திய புஷ்கள்" இருந்தன என்பதைக் குறிக்கும் பேனரைக் கண்டறிந்து, "ஒப்பிட்டு & புல் கோரிக்கை" பொத்தானைக் கிளிக் செய்யவும்.
  • PR உருவாக்கும் பக்கத்தை வலை உலாவியில் திறக்க, GitHub CLI gh pr create --web கட்டளையைப் பயன்படுத்தவும்.

GitHub CLI: gh

GitHub, (https://cli.github.com/) கட்டளை மூலம் உங்கள் டெர்மினலில் இருந்தே GitHub-இன் பல அம்சங்களை அணுக gh என்ற கருவியை வழங்குகிறது. GitHub CLI ஆவணங்கள் அனைத்து அம்சங்களையும் உள்ளடக்கியுள்ளது.

ஜிஎச் பிஆர் கிரியேட்

உங்கள் புல் ரிக்குவஸ்டை உருவாக்க, வெறும் gh pr create கட்டளையைப் பயன்படுத்த வேண்டாம். BeeWare திட்டங்கள் புல் ரிக்குவஸ்டுகளுக்கு ஒரு வார்ப்புருவைப் பயன்படுத்துகின்றன, மேலும் அனைத்து பங்களிப்புகளும் இந்த வார்ப்புருவைப் பின்பற்ற வேண்டும் என நாங்கள் எதிர்பார்க்கிறோம். gh pr create கட்டளை இந்த வார்ப்புருவின் பயன்பாட்டைத் தவிர்த்துவிடுகிறது.

இழு கோரிக்கை உள்ளடக்கம்

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

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

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

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

உங்கள் புல் ரிக்குவஸ்ட் சிக்கல் #1234-ஐத் தீர்க்கும் பட்சத்தில், உங்கள் புல் ரிக்குவஸ்ட் விளக்கத்தில் Fixes #1234 என்ற உரையைச் சேர்க்க வேண்டும். இது, புல் ரிக்குவஸ்ட் ஒன்றிணைக்கப்படும்போது, அந்தச் சிக்கல் தானாகவே மூடப்படுவதற்கு வழிவகுக்கும். இதே #1234 சொற்றொடையைப் பயன்படுத்தி நீங்கள் மற்ற கலந்துரையாடல்கள், சிக்கல்கள் அல்லது புல் கோரிக்கைகளைக் குறிப்பிடலாம். ஒரு எண்ணுக்கு முன்னால் - குறியைச் சேர்ப்பதன் மூலம் நீங்கள் வேறு ஒரு களஞ்சியத்தில் உள்ள ஒரு சிக்கலைக் குறிப்பிடலாம். உதாரணமாக, python/cpython#1234 என்பது CPython களஞ்சியத்தில் உள்ள சிக்கல் 1234-ஐக் குறிக்கும்.

AI கருவிகள், சோதனைத் தொகுப்பை எவ்வாறு இயக்குவது என்பதை விவரிக்கும் "சோதனை நெறிமுறை" அல்லது ஒரு பிழை ஏன் சரிசெய்யப்பட வேண்டும் என்பதற்கான "காரணம்" போன்ற, அதிகப்படியான, உதவாத புல் ரிக்வெஸ்ட் செய்திகளை எழுதுவதற்கு குறிப்பாக முனைகின்றன. உங்கள் PR-ஐ உருவாக்க நீங்கள் ஒரு AI கருவியைப் பயன்படுத்தினால், புல் ரிக்வெஸ்ட் விளக்கம் சுருக்கமாகவும், மதிப்பாய்வு செயல்முறைக்கு உதவக்கூடிய தகவல்களை மட்டுமே கொண்டிருப்பதை உறுதி செய்வதற்கும் நீங்களே பொறுப்பு. உதாரணமாக, சோதனைத் தொகுப்பை (test suite) எவ்வாறு இயக்குவது என்பதை விவரிக்கும் "சோதனை நெறிமுறை" அல்லது ஒரு பிழை ஏன் சரிசெய்யப்பட வேண்டும் என்பதற்கான "காரணம்" போன்ற விவரங்களை நீங்கள் சேர்க்க வேண்டியதில்லை. அளவுக்கு அதிகமாக நீளமான புல் ரிக்வெஸ்ட் உள்ளடக்கங்கள், முக்கிய குழுவின் வரையறுக்கப்பட்ட வளங்களைக் கருத்தில் கொள்ளாததால், உங்கள் புல் ரிக்வெஸ்ட் மதிப்பாய்வு செய்யப்படாமலேயே மூடப்படுவதற்கு வழிவகுக்கும்.

பீவேர் புல் ரிக்வெஸ்ட் வார்ப்புரு

BeeWare பல் ரிக்வெஸ்ட் வார்ப்புரு விருப்பத்திற்குரியது அல்ல. அனைத்து பல் ரிக்வெஸ்ட்களும் இந்த வார்ப்புருவைப் பின்பற்ற வேண்டும். உங்கள் பல் ரிக்வெஸ்டில் "PR சரிபார்ப்புப் பட்டியல்" பகுதி இல்லை என்றாலோ, அல்லது சரிபார்ப்புப் பெட்டி கேள்விகளுக்கான உங்கள் பதில்கள் முழுமையற்றதாகவோ அல்லது முரண்பாடாகவோ இருந்தாலோ, உங்கள் பல் ரிக்வெஸ்ட் மதிப்பாய்வு செய்யப்படாது. உங்கள் புல் கோரிக்கையை உருவாக்க நீங்கள் ஒரு AI கருவியைப் பயன்படுத்தியிருந்தால், நீங்கள் தொடர்புடைய பெட்டியை கட்டாயமாக தேர்வு செய்ய வேண்டும், மேலும் "Assisted-by:" என்ற வரிசையில் விவரங்களை வழங்க வேண்டும்.

தொடர் ஒருங்கிணைப்பு

தொடர் ஒருங்கிணைப்பு, அல்லது CI, என்பது உங்கள் புல் ரிக்குவஸ்டில் தானியங்கு சரிபார்ப்புகளை இயக்கும் செயல்முறையாகும். இதில் குறியீடு சரியாக வடிவமைக்கப்பட்டுள்ளதா என்பதை உறுதி செய்வது போன்ற எளிய சரிபார்ப்புகள் அடங்கும்; ஆனால் இது சோதனைத் தொகுப்பை இயக்குவது மற்றும் ஆவணங்களை உருவாக்குவதும் அடங்கும்.

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

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

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

ஒரு புதிய CI ஓட்டத்தைத் தூண்ட, உங்கள் கிளைக்கு புதிய மாற்றங்களைத் தள்ள வேண்டும்.

CI-ஐ கடக்க உங்களுக்கு உதவி தேவைப்படும் சூழ்நிலையில் நீங்கள் இருந்தால், PR-இல் ஒரு கருத்தைப் பதிவிட்டு எங்களுக்குத் தெரியப்படுத்துங்கள், நாங்கள் உதவ எங்களால் முடிந்ததைச் செய்வோம்.

pre-commit மற்றும் towncrier சரிபார்ப்புகள்

pre-commit அல்லது towncrier சரிபார்ப்புகளில் ஏதேனும் ஒன்று தோல்வியுற்றால், அது CI சரிபார்ப்புகளில் மீதமுள்ள பெரும்பாலானவற்றை இயங்குவதிலிருந்து தடுக்கும். முழுமையான சரிபார்ப்புகளும் இயங்குவதற்கு முன்பு, பொருந்தக்கூடிய சிக்கல்களை நீங்கள் சரிசெய்ய வேண்டும்.

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

உங்கள் PR சமர்ப்பிக்கும் செயல்முறை, அது CI-ஐ கடக்கும் வரை அல்லது அது ஏன் கடக்கவில்லை என்பதற்கான விளக்கத்தை நீங்கள் வழங்கும் வரை முழுமையடையாது.

ஒரு புல் ரிக்வெஸ்டைச் சமர்ப்பிப்பதன் ஒரு பகுதியாக, அது மதிப்பாய்வு செய்யப்படுவதற்கு முன்பு, நீங்கள் ஒரு மாற்றக் குறிப்பு-ஐ சேர்க்க வேண்டும்.