13.5. مستندات
از بهبود مستندات بسیار قدردانی میشود و این کار روشی عالی برای شروع مشارکت در Nix است.
در اینجا نحوه کمک کردن شما آمده است:
- رسیدگی به issues باز مربوط به مستندات
- بررسی pull requestهای مربوط به مستندات
بازسازیهای تدریجی فرآیند ساخت مستندات برای سریعتر کردن یا قابلفهمتر و نگهداریپذیرتر کردن آن نیز استقبال میشوند.
ساخت راهنما
ساخت راهنما از صفر:
nix-build -E '(import ./.).packages.${builtins.currentSystem}.nix.doc'یا
nix build .#nix-manualو ./result/share/doc/nix/manual/index.html را باز کنید.
برای ساخت تدریجی راهنما، به شل توسعه وارد شوید و با فعال بودن doc-gen پیکربندی کنید:
در صورت استفاده از nix develop تعاملی:
$ nix develop
$ mesonFlags="$mesonFlags -Ddoc-gen=true" mesonConfigurePhaseاگر از direnv استفاده میکنید:
$ direnv allow
$ bash -c 'source $stdenv/setup && mesonFlags="$mesonFlags -Ddoc-gen=true" mesonConfigurePhase'سپس راهنما را بسازید:
$ cd build
$ meson compile manualراهنمای HTML در مسیر build/src/nix-manual/manual/index.html تولید خواهد شد.
راهنمای نگارش
هدف از این راهنمای نگارش این است که:
- جستجو و مرور اجمالی اطلاعات مرتبط در راهنما آسان باشد
- ویرایش کدهای منبع مستندات ساده باشد
- بررسی تغییرات مستندات به سادگی انجام شود
متوجه خواهید شد که این موارد هنوز به طور یکدست پیادهسازی نشدهاند. لطفاً هنگام افزودن یا ایجاد تغییرات در مستندات موجود، از این راهنما پیروی کنید. تغییرات اساسی و گسترده ایجاد نکنید، مگر اینکه خودکار (برنامهنویسیشده) باشند و به راحتی قابل اعتبارسنجی باشند.
زبان
این راهنما یک مستندات مرجع است. الگوی استفادهی رایج این است که قطعات مجزای اطلاعات جستجو شوند. بنابراین باید تلاش شود که دقیق، سازگار، کامل و با یک نگاه قابل ناوبری باشد.
وضوح و اختصار را هدف قرار دهید.
لطفاً برای جزئیات، زمانی را به مطالعهی دستورالعملهای زبان ساده اختصاص دهید.
موضوع را به صورت واقعی و بدون جانبداری توصیف کنید.
بهویژه، قضاوت ارزشی یا توصیه ارائه نکنید. در صورت شک، کد را بررسی کنید یا تست اضافه کنید.
مثالهای کامل و حداقلی ارائه دهید و آنها را توضیح دهید.
خوانندگان باید بتوانند مثالها را عیناً امتحان کنند و همان نتایج نشاندادهشده در راهنما را دریافت کنند. همیشه با کلمات توصیف کنید که یک مثال مشخص چه کاری انجام میدهد.
مثالهای غیربدیهی ممکن است نیاز به توضیح اضافی داشته باشند، بهویژه اگر از مفاهیمی خارج از زمینه مشخصشده استفاده کنند.
همیشه مثالهای کد را در متن توضیح دهید.
از کامنتها در نمونهکدها بسیار صرفهجویی کنید، مثلاً برای برجسته کردن یک جنبه خاص. خوانندگان تمایل دارند هنگام اسکن کردن اطلاعات، از روی کدهای حجیم به سرعت بگذرند.
بهویژه مبتدیان احتمالاً خواندن کدهای پیچیدهبهنظررسنده را طاقتفرسا میدانند و بنابراین ممکن است کلی از آن اجتناب کنند.
اگر به نظر میرسد یک نمونهکد نیاز به توضیحات درونخطی زیادی دارد، جایگزین کردن آن با یک نمونه سادهتر را در نظر بگیرید. اگر این کار ممکن نیست، مثال را به چند بخش تقسیم کنید، آنها را بهصورت جداگانه توضیح دهید و سپس نتیجهی ترکیبی را در انتها نشان دهید. این باید آخرین راهحل باشد، زیرا به منزلهی نوشتن یک آموزش در مورد موضوع دادهشده خواهد بود.
از انگلیسی بریتانیایی استفاده کنید.
این یک انتخاب نسبتاً اختیاری برای اجبار به حفظ سازگاری است و این حقیقت را در نظر میگیرد که اکثریت کاربران و توسعهدهندگان Nix اهل اروپا هستند.
پیوندها و لنگرها
مستندات مرجع باید به هر ترتیبی قابل خواندن باشند. نمیتوان انتظار داشت که خوانندگان هیچ دانش پیشنیاز خاصی در مورد Nix داشته باشند. در حالی که فهرست مطالب میتواند راهنمایی کند و جستجوی تماممتن مفید باشد، آنها احتمالاً با دنبال کردن پیوندهای متقابل معقول، آنچه را که نیاز دارند پیدا خواهند کرد.
به اصطلاحات فنی پیوند دهید
هنگام ذکر مفاهیم، دستورات، گزینهها، تنظیمات و غیره که مخصوص Nix هستند، به مستندات مناسب پیوند دهید. همچنین به ابزارها یا مفاهیم خارجی، بهویژه اگر معنای آنها مبهم باشد، پیوند دهید. همچنین ممکن است بخواهید به تعاریف اصطلاحات فنی کمتر رایج پیوند دهید.
در این صورت خوانندگان مجبور نخواهند بود به طور فعال به دنبال تعاریف بگردند و احتمال اینکه اطلاعات مربوطه را خودشان کشف کنند بیشتر است.
نکته
صفحات
manو--helpپیوندها را نمایش نمیدهند. از متنهای پیوند مناسبی استفاده کنید تا خوانندگان خروجی پایانه بتوانند اصطلاحات جستجو را استنباط کنند.URLs موجود را بین نسخههای مختلف خراب نکنید.
پیوندهای بیشماری در فضای وب وجود دارد که به نسخههای قدیمی راهنما اشاره میکنند. ما میخواهیم افراد هنگام دنبال کردن توصیههای محبوب، مستندات بهروز را پیدا کنند.
هنگام جابجایی فایلها، تغییرمسیرهای موجود در nixos.org را بهروزرسانی کنید.
این کار بهویژه هنگام انتقال اطلاعات از راهنمای Nix به منابع دیگر اهمیت دارد.
هنگام تغییر لنگرها (anchors)، تغییرمسیرهای سمت کاربر را بهروزرسانی کنید.
پیکربندی فعلی دستوپاگیر است و از کمک برای ساخت اتوماسیون بهتر استقبال میشود.
فرآیند ساخت، لینکهای داخلی خراب را بررسی میکند.
این اتفاق در اواخر فرآیند رخ میدهد، بنابراین ساخت کل راهنما برای تکرار سریع مناسب نیست.
ابزار mdbook-linkcheck هنوز بررسی [فرگمنتهای URI] را پیادهسازی نکرده است.
قراردادهای Markdown
این راهنما با استفاده از Markdown نوشته شده و با mdBook برای وب و با lowdown برای صفحات راهنما (man pages) و خروجی --help رندر میشود.
برای اطلاع از قابلیتهای پشتیبانیشدهی Markdown، به موارد زیر مراجعه کنید:
لطفاً برای تسهیل بررسیها، این دستورالعملها را رعایت کنید:
در هر خط، دقیقاً یک جمله بنویسید.
این کار باعث میشود جملات طولانی بلافاصله قابلمشاهده باشند و بررسی تغییرات و ارائه پیشنهادات مستقیم آسانتر شود.
برای خوانایی بهتر کد منبع، از لینکهای ارجاعی – به میزان کم – استفاده کنید. تعاریف را نزدیک به اولین استفادهی آنها قرار دهید.
مثال:
A [store object] contains a [file system object] and [references] to other store objects.
[store object]: store/store-object.md
[file system object]: architecture/file-system-object.md
[references]: glossary.md#gloss-reference- از یادداشتهای هشدار و راهنمایی (Admonitions) به فرم زیر استفاده کنید:
> **Note**
>
> This is a note.نمونههای برجستهسازیشده را به این صورت نشان دهید:
> **Example**
>
> ```console
> $ nix --version
>
```
```تعاریف نحو را به این شکل و با استفاده از علامتگذاری [EBNF](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form) برجسته کنید:
```
> **Syntax**
>
> *attribute-set* = `{` [ *attribute-name* `=` *expression* `;` ... ] `}`
```### متغیر ``
متغیر `` یک مسیر پایه برای پیوندهایی فراهم میکند که در قطعهکدهای قابل استفاده مجدد یا سایر مستنداتی ظاهر میشوند که خودشان مسیر پایه ندارند.
اگر یک پیوند شکسته در قطعهکدی رخ دهد که در چندین فایل تولیدشده در پوشههای مختلف درج شده است، از `` برای ارجاع به پوشه `doc/manual/source` استفاده کنید.
اگر نویسهٔ تحتاللفظی `` در یک پیام خطا از ابزار [`mdbook-linkcheck`] ظاهر شود، لازم است جایگزینی `` روی فایل منبع تولیدشدهای که به آن اشاره میکند اعمال شود.
منطق موجود `` را در [Makefile for the manual] مشاهده کنید.
فایلهای استاندارد Markdown مورد استفاده برای راهنما، مسیر پایه خود را دارند و میتوانند بهجای `` از مسیرهای نسبی استفاده کنند.
## مستندات API
[مستندات API دایوژن (Doxygen)][Doxygen API documentation] بهصورت آنلاین در دسترس است.
همچنین میتوانید خودتان آن را بسازید و مشاهده کنید:
[Doxygen API documentation]: https://hydra.nixos.org/job/nix/master/internal-api-docs/latest/download-by-type/doc/internal-api-docs
```shell
$ nix build .#hydraJobs.internal-api-docs
$ xdg-open ./result/share/doc/nix/internal-api/html/index.html
```
یا داخل `nix-shell` یا `nix develop`:
```shell
$ configurePhase
$ ninja src/internal-api-docs/html
$ xdg-open src/internal-api-docs/html/index.html
```
## مستندات C API
توجه داشته باشید که C API هنوز پایدار نیست.
[مستندات C API] به صورت آنلاین در دسترس است.
همچنین میتوانید آن را خودتان بسازید و مشاهده کنید:
[مستندات C API]: https://hydra.nixos.org/job/nix/master/external-api-docs/latest/download-by-type/doc/external-api-docs
```shell
$ nix build .#hydraJobs.external-api-docs
$ xdg-open ./result/share/doc/nix/external-api/html/index.html
```
یا درون `nix-shell` یا `nix develop`:
```
$ configurePhase
$ ninja src/external-api-docs/html
$ xdg-open src/external-api-docs/html/index.html
```
اگر از direnv استفاده میکنید، یا به هر نحو دیگری میخواهید `configurePhase` را در یک شل موقت (transient shell) اجرا کنید، از این دستور استفاده کنید:
```bash
nix-shell -A devShells.x86_64-linux.native-clangStdenv --command 'appendToVar mesonFlags "-Ddoc-gen=true"; mesonConfigurePhase'
```