forked from sergey-s-betke/ITG.Readme
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ITG.Readme.psd1
180 lines (129 loc) · 9.94 KB
/
ITG.Readme.psd1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
#
# Манифест модуля для модуля "ITG.Readme".
#
# Создано: Sergey S. Betke
#
# Дата создания: 13.11.2012
#
# Архив проекта: https://github.com/IT-Service/ITG.Readme
#
@{
# Файл модуля скрипта или двоичного модуля, связанный с данным манифестом
RootModule = 'ITG.Readme.psm1'
# Номер версии данного модуля.
ModuleVersion = '2.3.2'
# Уникальный идентификатор данного модуля
GUID = '826e836c-d10c-4d4d-b86b-8b4a41829b00'
# Автор данного модуля
Author = 'Sergey S. Betke'
# Компания, создавшая данный модуль, или его поставщик
CompanyName = 'IT-Service.Nov.RU'
# Заявление об авторских правах на модуль
Copyright = '(c) 2012 Sergey S. Betke. All rights reserved.'
# Описание функций данного модуля
Description = @'
Данный модуль предоставляет набор командлет для формирования **справочной системы** модулей
PowerShell, сценариев PowerShell:
- генерация **readme.md** (readme.txt) файла для модуля, сценария;
- генерация файла **about_ModuleName.txt** для модуля;
- генерация **xml справки** для модуля (включая .cab файлы, см. about_Updatable_Help).
Для генерации указанных выше элементов справочной системы используется справка, построенная
на основе комментариев в тексте описываемого модуля, сценария (см. about_Comment_Based_Help).
В качестве примера использования функционала данного модуля можно рассматривать справочную
систему этого же модуля. В частности, файла **readme.md** в корневом каталоге репозитория сгенерирован
следующим образом:
Get-Module 'ITG.Readme' `
| Set-Readme `
;
Командлет Set-Readme по умолчанию генерирует файл с именем `readme.md` в каталоге модуля.
Формат генерируемого Readme.MD файла - текстовый файл в кодировке UTF-8 с
разметкой MarkDown.
Хорошим тоном считается предоставлять локализованный файл с кратким описанием функциональности
модуля - **about_ModuleName.txt**. Данный файл должен быть размещён в подкаталоге культуры корневого
каталога описываемого модуля. Например, следующий код генерирует указанный файл для модуля `ITG.Readme`:
Get-Module 'ITG.Readme' | Set-AboutModule;
В результате получаем файл `about_ITG.Readme.txt` в подкаталоге `ru-RU` корневого каталога модуля
`ITG.Readme`. Для чего? И вот для чего:
Get-Help about_ITG.Readme
или
Get-Module 'ITG.Readme' | Get-Help
выдаст содержимое созданного `about_ITG.Readme.txt` файла
в необходимом пользователю языке (естественно, если необходимая локализация есть в наличии).
Порядок традиционный: в первую очередь
осуществляется попытка обнаружить указанный выше файл в каталоге текущей культуры пользователя
(для русского языка - 'ru-RU'), если же такого подкаталога или файла в нём нет, тогда - по правилам
подбора наиболее подходящей локализации, вплоть до 'en-US'.
И на десерт - генерация обновляемой загружаемой **xml справки**:
Get-Module 'ITG.Readme' `
| Set-HelpXML -Cab -PassThru `
| Set-HelpInfo `
;
Чтобы понять, о чём идёт речь, следует изучить раздел справочной системы PowerShell about_Comment_Based_Help.
приведённый выше код генерирует локализуемую xml справку в подкаталогах культуры (в случает данного модуля -
`ru-RU\ITG.Readme-help.xml`), и при необходимости (параметр `-Cab`) генерирует загружаемый архив (файл
`help.cab\ITG.Readme_826e836c-d10c-4d4d-b86b-8b4a41829b00_ru-RU_HelpContent.cab`).
Для поддержки `Update-Help` ещё необходим файл `ITG.Readme_826e836c-d10c-4d4d-b86b-8b4a41829b00_HelpInfo.xml`,
который и генерируется командлетом Set-HelpInfo.
После того, как xml файлы справки сгенерированы, необходимо внести изменения в файлы модуля и его манифеста.
Эти действия так же могут быть выполнены сценарием:
Get-Module 'ITG.Readme' `
| Set-HelpXML -Cab -UpdateModule `
| Set-HelpInfo -UpdateManifest `
;
Функции данного модуля так же позволяют Вам генерировать перекрёстные ссылки на описания используемых
Вами функций. Например, данная ссылка - Get-Command сгенерирована автоматически.
Ссылки формируются на описания функций и командлет модулей 'Microsoft.PowerShell.*', тех модулей, которые
Вы явно указали как необходимые в манифесте Вашего модуля (`RequiredModules`), а также на описания
функций тех модулей, что Вы явно указали в параметре `ReferencedModules`.
P.S. Надеюсь, функционал данного модуля будет Вам полезен и позволит обеспечить Ваши модули PowerShell
документацией с существенно меньшими трудозатратами.
Тестирование модуля и подготовка к публикации
---------------------------------------------
Для сборки модуля использую проект [psake](https://github.com/psake/psake). Для инициирования сборки используйте сценарий `build.ps1`.
'@
# Минимальный номер версии обработчика Windows PowerShell, необходимой для работы данного модуля
PowerShellVersion = '3.0'
# Имя узла Windows PowerShell, необходимого для работы данного модуля
PowerShellHostName = ''
# Минимальный номер версии узла Windows PowerShell, необходимой для работы данного модуля
PowerShellHostVersion = ''
# Минимальный номер версии компонента .NET Framework, необходимой для данного модуля
DotNetFrameworkVersion = '2.0'
# Минимальный номер версии среды CLR (общеязыковой среды выполнения), необходимой для работы данного модуля
CLRVersion = '2.0'
# Архитектура процессора (нет, X86, AMD64, IA64), необходимая для работы модуля
ProcessorArchitecture = ''
# Модули, которые необходимо импортировать в глобальную среду перед импортированием данного модуля
RequiredModules = @(
@{ModuleName = 'ITG.RegExps'; ModuleVersion = '1.1'} `
)
# Сборки, которые должны быть загружены перед импортированием данного модуля
RequiredAssemblies = @()
# Файлы скрипта (.ps1), которые запускаются в среде вызывающей стороны перед импортированием данного модуля
ScriptsToProcess = @()
# Файлы типа (.ps1xml), которые загружаются при импорте данного модуля
TypesToProcess = @()
# Файлы формата (PS1XML-файлы), которые загружаются при импорте данного модуля
FormatsToProcess = @()
# Модули для импортирования в модуль, указанный в параметре ModuleToProcess, в качестве вложенных модулей
NestedModules = @()
# Функции для экспорта из данного модуля
FunctionsToExport = '*'
# Командлеты для экспорта из данного модуля
CmdletsToExport = '*'
# Переменные для экспорта из данного модуля
VariablesToExport = '*'
# Псевдонимы для экспорта из данного модуля
AliasesToExport = '*'
# Список всех модулей, входящих в пакет данного модуля
ModuleList = @()
# Список всех файлов, входящих в пакет данного модуля
FileList = `
'ITG.Readme.psm1' `
, 'ITG.Readme.psd1' `
, 'readme.md'
# Личные данные, передаваемые в модуль, указанный в параметре ModuleToProcess
PrivateData = @{
ReadmeURL = 'https://github.com/IT-Service/ITG.Readme';
}
}