مولد مساعدة PowerShell MAML

Question

هل يعرف أي شخص فائدة لتوليد ملفات مساعدة PowerShell CMDLET؟ يبدو أن القيام بذلك باليد مملة بعض الشيء ...

أنا موجود: http://blogs.msdn.com/powershell/archive/2007/09/01/new-and-improved-cmdlet-help-editor-tool.aspx

أي إصدارات محدثة؟ لا يمكنني تحديد وحدة نمطية. لدي وحدة ثنائية.

Answer 1

لقد قمت بإنشاء برنامج نصي PowerShell من شأنه أن يولد MAML لـ CMDLETS والوظائف بغض النظر عما إذا كانت جزءًا من الوحدات النمطية. إنه ليس مثاليًا لأن MAML المولدة سيتطلب بعض التحرير اليدوي ، ولكن أيضًا محرر مساعدة CMDLET الذي أشرت إليه. لدي منشور مدونة حول هذا الموضوع هنا

إذا كنت تستخدمه ووجدت أن التصحيحات لا تتردد في التحديث السيناريو على الرمز الفاخرة.

Answer 2

اضطررت إلى توثيق الوحدة النمطية الخاصة بي ولم أجد أي حل أفضل من إنشاء منشئ مساعدة MAML الخاص بي. ها هو:https://github.com/nightroman/helps

تبني الوحدة ملفات مساعدة PowerShell MAML من PowerShell Help Scripts. نصوص المساعدة هي تقريبا wysiwyg ، فهي تشبه إلى حد كبير مساعدة النتيجة. ومع ذلك ، فهي مجرد نصوص وهذا يجعل الكثير من الميزات المفيدة سهلة. واحد منهم هو بناء ملفات مساعدة للعديد من الثقافات.

فيما يلي قالب بيانات المساعدة للأوامر (cmdlet ، الوظائف ، البرامج النصية) ومقدمي الخدمات:

### Command help data

@{
    command = 'Name'
    synopsis = '...'
    description = '...'
    sets = @{
        Set1 = '...'
        #...
    }
    parameters = @{
        Param1 = '...'
        #...
    }
    inputs = @(
        @{
            type = '...'
            description = '...'
        }
        #...
    )
    outputs = @(
        @{
            type = '...'
            description = '...'
        }
        #...
    )
    notes = '...'
    examples = @(
        @{
            title = '...'
            introduction = '...'
            code = {
            }
            remarks = '...'
            test = {
                . $args[0]
            }
        }
        #...
    )
    links = @(
        @{
            text = '...'
            URI = '...'
        }
        #...
    )
}

### Provider help data

@{
    provider = 'Name'
    drives = '...'
    synopsis = '...'
    description = '...'
    capabilities = '...'
    tasks = @(
        @{
            title = '...'
            description = '...'
            examples = @(
                @{
                    title = '...'
                    introduction = '...'
                    code = {
                    }
                    remarks = '...'
                    test = {
                        . $args[0]
                    }
                }
            )
        }
        #...
    )
    parameters = @(
        @{
            name = '...'
            type = '...'
            description = '...'
            cmdlets = '...'
            values = @(
                @{
                    value = '...'
                    description = '...'
                }
                #...
            )
        }
        #...
    )
    notes = '...'
    links = @(
        @{
            text = '...'
            URI = '...'
        }
        #...
    )
}

Answer 3

لقد كنت أبحث في طريقة لتضمين الوثائق في رمز Snapin/Module C# و poshbuild بدأ يبدو وكأنه أفضل خياري. لا يوفر طريقة لتضمين بعض عناصر الوثائق (على سبيل المثال ، ملخص وأمثلة) ، لكنه لا يزال خيارًا جيدًا.

Answer 4

من حيث الأدوات الرسومية لتحرير مساعدة XML PowerShell (PSMAML) يمكنك استخدام:

• محرر مساعدة PowerShell Cmdlet (المصدر المفتوح ، شيء من الخلف الروحي لمحرر مساعدة CMDLT).
• PowerShell وكاتب المساعدة (تجاري).

Answer 5

مع ظهور المصدر المفتوح XMLDOC2CMDLETDOC, ، يمكنك الآن توثيق الخاص بك الثنائية PowerShell Cmdlets (أي تلك المكتوبة في C#) تمامًا مثل أي مكتبات C# ، ومثلها تمامًا نصوص cmdlets (تلك المكتوبة في PowerShell): استخدم تعليقات الوثائق المضمنة.

لم تعد بحاجة إلى الحفاظ على موازاة MAML ملف باليد! فقط قم بإنشاء إنشاءك بحيث عند إعادة ترجمة مشروع C# الخاص بك ، فإنه ينفذ مولد التوثيق وتحصل على كل من وحدة.DLL و وحدة.dll-help.xml. يتم استخدام هذا الأخير مباشرة من قبل PowerShell لتقديم المساعدة على cmdlets الخاص بك عند استدعاء Get-Help.

و XMLDOC2CMDLETDOC حتى يقدم -strict قم بالتبديل للتأكد من أنك قد قمت بتوثيق cmdlets بشكل شامل ؛ إذا كنت تستخدم المفتاح وفقدت شيئًا ما ، فسوف يفشل بناءك ، كما ينبغي.

الفوائد الأخرى التي توفرها تلقائيًا بواسطة XMLDOC2CMDLETDOC (تشير "الأقسام" في هذه القائمة إلى أقسام المساعدة المقدمة بواسطة Get-Help):

• كل نوع مخصص في المخرجات يتضمن القسم وصفًا.
• ال بناء الجملة يتضمن القسم قيمًا محتملة للأنواع المخصصة.
• ال معامل يتضمن القسم قيمًا محتملة للأنواع المخصصة.
• تم توثيق الأسماء المستعارة تلقائيًا في المعلمات الجزء.
• يتم التعامل مع الأسماء المستعارة كمعلمات من الدرجة الأولى حتى تتمكن من طلب المساعدة على الاسم المستعار.
• يمكنك اختياريًا استخدام وصف مختلف للمعلمة في المدخلات القسم كما لديك ل معامل الجزء.
• يتم تقديم روابط الويب تلقائيًا بتنسيق Markdown ، لإمكانية معالجة ما بعد المعالجة المحتملة إلى الروابط الحية. (هذا التعزيز معلق.)

لقد أحببت هذه الأداة المساعدة المفتوحة المصدر كثيرًا ، لقد بدأت المساهمة في ذلك ، وتوفير العديد من الفوائد المذكورة أعلاه. وكتبت دليلًا شاملاً لاستخدامه ، بعنوان توثيق PowerShell الثنائي cmdlets, ، تم نشره للتو على simple-talk.com.