تطبيقات ومكتبات

Golds

Golds خادم تجريبي لتوثيق Go المحلي، ومولِّد توثيق Go، وقارئ شيفرة Go.

  • عرض توضيحي: توثيق وشيفرة المصدر للحزم القياسية (مولَّد باستخدام GOEXPERIMENT=arenas,jsonv2 golds -gen -nouses -only-list-exporteds -render-doclinks -theme=dark std).
  • الشيفرة مستضافة على GitHub. نرحّب بأي ملاحظات، بما في ذلك طلبات السحب (PR) وتقارير الأخطاء.
  • تابع @zigo_101 للحصول على آخر أخبار Golds (وكل أنواع تفاصيل/حقائق/نصائح Go وغيرها).

الميزات والقيود

يرجى قراءة الصفحة الرئيسية للمشروع للتفاصيل.

التثبيت

نفّذ go install go101.org/golds@latest لتثبيت Golds. إذا تعارض اسم برنامج الأداة golds مع أداة أخرى تحمل الاسم نفسه وتستخدمها، فيمكنك تنفيذ أي من الأوامر التالية لتثبيت Golds كبرنامج باسم مختلف:

  • مولِّد توثيق Go: نفّذ go install go101.org/golds/godoge@latest
  • قارئ شيفرة Go: نفّذ go install go101.org/golds/gocore@latest
  • توثيق Go المحلي (أساساً للتوافق مع القديم. كان gold الاسم الافتراضي القديم لبرنامج Golds): نفّذ go install go101.org/golds/gold@latest

يمكنك أيضاً استنساخ هذا المشروع أولاً، ثم تنفيذ أمر go install في مجلدات البرامج المعنية لتثبيت Golds باسم golds أو godoge أو gocore.

(ملاحظة: ستثبّت أوامر Go الملفات التنفيذية الناتجة في مسار تثبيت الملفات التنفيذية لـ Go المحدَّد بمتغير البيئة GOBIN، والذي يكون افتراضياً مسار المجلد الفرعي bin ضمن أول مسار محدَّد في متغير البيئة GOPATH، والذي يكون افتراضياً مسار المجلد الفرعي go ضمن المسار المحدَّد بمتغير البيئة HOME. يرجى تحديد مسار تثبيت الملفات التنفيذية لـ Go في متغير البيئة PATH لتشغيل أوامر Golds بنجاح.)

الاستخدامات

الاستخدام الرئيسي لـ Golds هو تشغيل خادم توثيق محلي لمشروع، إما لقراءة توثيق الحزم أو لدراسة شيفرة المشروع المصدرية. يمكننا

  • تنفيذ golds . لعرض توثيق الحزمة في المجلد الحالي (وجميع حزمها التابعة).
  • تنفيذ golds ./... لعرض توثيق جميع الحزم ضمن المجلد الحالي (وجميع حزمها التابعة).
  • تنفيذ golds toolchain (أو golds cmd) لعرض توثيق حزم سلسلة الأدوات الرسمية.
  • تنفيذ golds std لعرض توثيق الحزم القياسية. يمكن مزج std مع أي واحد من المعطيات الثلاثة أعلاه.
  • تنفيذ golds aPackage[/...][@aVersion] لعرض توثيق الحزم المحدَّدة (وجميع حزمها التابعة).
  • تنفيذ golds foo.go bar.go baz.go لعرض توثيق الملفات المحدَّدة (وجميع حزمها التابعة).

سيفتح كل أمر من الأوامر أعلاه نافذة متصفح تلقائياً. ويمكننا استخدام الخيارين -s أو -silent لإيقاف هذا السلوك.

الاستخدام الثاني لـ Golds هو توليد صفحات توثيق HTML ثابتة لمشروع، باستخدام الخيار -gen:

  • golds -gen -dir=generated -nouses .
  • golds -gen -dir=generated -nouses ./...
  • golds -gen -dir=generated -nouses std

الخيار -dir اختياري وقيمته الافتراضية هي .(مجلد العمل). والخيار -nouses المستخدم هنا هو لتوليد توثيق بأحجام معتدلة.

يُستخدم الخيار -source-code-reading للتحكم في كيفية توليد صفحات الشيفرة المصدرية. القيم المتاحة:

  • plain: توليد صفحات شيفرة مصدرية أبسط (بلا تظليل وبلا تنقّلات في الشيفرة لتقليل حجم الصفحة الإجمالي بمقدار 1/6 من حجم التوثيق الكامل).
  • highlight: تظليل الكلمات المفتاحية والقيم الحرفية الأساسية فقط (بلا تنقّلات في الشيفرة).
  • rich: تجربة قراءة شيفرة غنية.
  • external: الربط بمواقع استضافة الشيفرة الخارجية (تبذل قصارى جهدها، وتستخدم highlight عند الفشل).

يحدِّد الخيار -allow-network-connection ما إذا كانت اتصالات الشبكة مسموحاً بها أم لا عند تحديد مواقع استضافة الشيفرة الخارجية.

خيارات التحكم في أحجام التوثيق المولَّد:

  • -nouses: عدم توليد صفحات استخدامات المعرّفات (ستشغل صفحات استخدامات المعرّفات نحو 9/10 من إجمالي عدد الصفحات و2/3 من حجم التوثيق الكامل).
  • -source-code-reading=plain
  • -only-list-exporteds: عدم سرد عناصر الشيفرة غير المصدَّرة على مستوى الحزمة في صفحات تفاصيل الحزمة.
  • -compact اختصار لمجموعة خيارات توليد التوثيق المضغوط أعلاه.
  • استخدام -source-code-reading=external مع -compact سيقلّل أكثر من حجم التوثيق المولَّد.

حجم التوثيق المولَّد بواسطة golds -gen -compact ./... يقارب 1/6 من حجم golds -gen ./... ونحو 1/2 من حجم golds -gen -nouses ./.... وحجم التوثيق المولَّد بواسطة golds -gen -compact -source-code-reading=external ./... يقارب 1/6 من حجم golds -gen -compact ./....

يُستخدم الخيار -wdpkgs-listing لتحديد كيفية سرد الحزم في مجلد العمل. تتضمن القيم المتاحة

  • general (القيمة الافتراضية، سردها مع غيرها بترتيب أبجدي)
  • promoted (سردها قبل غيرها)
  • solo (سردها وحدها دون غيرها)

يُستخدم الخيار -render-doclinks للتحكم في ما إذا كانت الروابط ستُعرض في التوثيق أم لا.

يُستخدم الخيار -theme للتحكم في تنسيق الصفحة. تتضمن القيم المدعومة auto (الافتراضية) وlight وdark. القيمة auto مكافئة لـ light مضافاً إليها تنسيق مخصص محدَّد في الملف UserConfigDir/golds/custom.css (إن وُجد).

الاستخدام الثالث لـ Golds هو تقديم الملفات ضمن مجلد («Golds» تعني أيضاً خادم الدليل المحلي لـ Go). على سبيل المثال، يمكننا تنفيذ golds -dir=. (أو ببساطة golds) من مجلد توليد توثيق HTML لعرض التوثيق المولَّد في المتصفح. ويعمل الخياران -s و-silent أيضاً في هذا النمط.

يتعرّف أمر golds على متغيري البيئة GOOS وGOARCH.

الأسئلة الشائعة

ماذا يعني اسم Golds؟

«Golds» اختصار لعبارة «Go local docs server» (خادم توثيق Go المحلي). وهي تعني أيضاً «Go local directory server» (خادم الدليل المحلي لـ Go).

لماذا Golds؟

لم أجد أداة Go تعرض علاقات تنفيذ الأنواع، فقررت كتابة واحدة. وأثناء تحقيق ذلك، خطرت لي أفكار جديدة كثيرة صاغت الأداة في تصميم Golds النهائي.

ولديّ أيضاً آراء تصميمية تختلف عن آراء مطوّري برنامج godoc الرسمي، مثل طريقة إدراج دوال المصنع.

ويحاول Golds أيضاً إصلاح بعض أوجه القصور الأخرى في godoc وgo doc، مثل هذا وهذا وهذا.

هل يُنصح بتشغيل Golds محلياً؟

نعم. لكن إذا أردت فعلاً تقديم توثيق حزمك على الإنترنت، فمن الأفضل تقديم صفحات توثيق HTML الثابتة المولَّدة لتقليل تكلفة الخادم.

ما متطلبات تشغيل Golds؟

إذا احتاج مشروع Go إلى cgo، فيلزم مصرِّف C/C++ مناسب.

قد تحتاج بعض المشاريع إلى سعة ذاكرة كبيرة لتحليلها. على سبيل المثال، سعة الذاكرة الموصى بها لتحليل مشروع Kubernetes هي 8G+. ومع ذلك، تكفي ذاكرة تتراوح بين 500M و2G لمعظم مشاريع Go.