Чтобы показать, как создавать документацию, которая входит в Центр документации, мы создадим пакет, который содержит очень простые функции и его документацию.Позвоните нашему пакету SOPackage.Этот пакет будет храниться в папке с тем же именем, и такая папка должна храниться либо в $BaseDirectory, либо в $UserBaseDirectory$.Папка SOPakage должна иметь следующую древовидную структуру.
Обратите внимание, что корнем является каталог SOPackage.
SOPackage
Теперь мы создадим новый файл блокнота внутри SOPackage: SOPackage.nb.Это содержимое записной книжки
BeginPackage["SOPackage`"];
AddTwo::usage = "AddTwo[\!\(\*StyleBox[\"a\", \"TI\"]\), \!\(\*StyleBox[\"b\", \"TI\"]\)] returns \!\(\*StyleBox[\"a\", \"TI\"]\)+\!\(\*StyleBox[\"b\", \"TI\"]\).";
DotTwo::usage = "DotTwo[\!\(\*StyleBox[\"a\", \"TI\"]\), \!\(\*StyleBox[\"b\", \"TI\"]\)] returns \!\(\*StyleBox[\"a\", \"TI\"]\)*\!\(\*StyleBox[\"b\", \"TI\"]\).";
AddTwo::argnum = "AddTwo was called with `1` arguments. It expected 2.";
DotTwo::argnum = "DotTwo was called with `1` arguments. It expected 2.";
Begin["`Private`"];
AddTwo[a_, b_] := a + b
AddTwo[args___] := (Message[AddTwo::argnum, Length[{args}]]; $Failed)
DotTwo[a_, b_] := a*b
DotTwo[args___] := (Message[DotTwo::argnum, Length[{args}]]; $Failed)
End[];
EndPackage[];
Вот скриншот того, что вы должны увидеть
Обратите внимание, что сообщения об использовании обычно форматируют параметры вособый способ.Ярлык для получения этого формата (на который указывает @ alexey-popkov) состоит в том, чтобы выделить букву, которую вы хотите отформатировать, нажмите Command + 0 ( Alt + 0 в окнах) и введите"TI".Повторите этот процесс для всех букв, которые необходимо изменить.Измените ячейку на ячейку инициализации с помощью Cell->CellProperties->Initialization Cell.Теперь мы сохраняем этот блокнот как SOPackage.nb.В случае, если Mathematica не спросит вас, хотите ли вы создать пакет, потому что вы забыли изменить ячейку на ячейку инициализации, тогда вы можете перейти к Format->OptionInspector.Убедитесь, что вы выбираете «Параметры для SOPackage.nb», в противном случае параметр, который необходимо установить в значение true, будет недоступен.Теперь нажмите Notebook Options->FileOptions->AutoGeneratedPackage и выберите Automatic.Закройте окно параметров и сохраните файл.Каждый раз, когда вы сохраняете SOPackage.nb, файл SOPackage.m будет обновляться (не связывайтесь с этим m файлом).
Каталог Kernel должен содержать только один файл: init.m.Этот файл должен иметь следующую строку:
Get["SOPackage`SOPackage`"];
После этого у нас есть рабочий пакет.Вы можете попробовать следующее, чтобы убедиться, что все работает нормально:
<<SOPackage`
?AddTwo
?DotTwo
DotTwo[]
DotTwo[2, 3]
Документация
Позволяет нам начать с создания страницы руководства.Это будет страница, которая будет отображаться при вводе SOPackage в центре документов.Начнем с создания блокнота и сохранения его под SOPackage/Documentation/English/Guides как SOPackage_E.nb.Причина, по которой я даю ему расширение "_E", заключается в том, что это будет редактируемая копия.Обратите внимание, что вы не можете редактировать какие-либо документы в центре документации.Ну, вы можете, но эти изменения никогда не вступают в силу.Вы, вероятно, захотите изменить свою документацию при сборке пакета, поэтому рекомендуется иметь копию, которую можно редактировать.Для этого примера мы можем скопировать содержимое Combinatorica guide, в центре Doc типа Combinatorica/guide/CombinatoricaPackage выбрать все с ячейками, скопировать и вставить их в файл SOPackage_E.nb (альтернативно, скопировать файл C:\Program Files\Wolfram Research\Mathematica\10.4\Documentation\English\Packages\Combinatorica\Documentation\English\Guides\CombinatoricaPackage.nb или что-то аналогичное надругие ОС).Сделайте некоторые изменения, чтобы вы знали, что это те, кого вы делаете.В моем случае я заменил Combinatorica на SOPackage.В случае, если вы не можете изменить некоторую часть текста, это то, что вам нужно сделать:
1: Нажмите на текст, который вы не можете изменить.
2: перейдите к Cell->Show Expression или введите Command+Shift+E или что-то эквивалентное в Windows.
3: найдите второй аргумент в выражении Cell (справаперед любыми опциями формы A -> B).Это название стиля.В некоторых случаях вы увидите «Использование», «Заметки», «ObjectName» среди других.Найдя стиль ячейки, который вы не можете изменить, нажмите на записную книжку, которую вы редактируете, и введите Command+Shift+E, чтобы отобразить выражение.
4: Перейдите к Format->Edit StyleSheet..., введите название стиля, которое вывидел ранее под Enter a style name:.
5: появляется ячейка, показывающая стиль.Убедитесь, что эта ячейка выбрана, и перейдите к Format->Object Inspector.Убедитесь, что написано Show option values Выбор .
6: Перейдите к Editing Options и установите Editable в true.
7: Изменить неизменяемое.
Я предлагаю вам сначала ввести имя всех стилей, которые вы хотите редактировать, как я показал на скриншоте.До сих пор я изменил только те, которые я упомянул на шаге 3. Как только они появятся в списке, выберите их все и сразу установите для редактирования.Еще одним важным моментом является то, что этот файл может быть шаблоном.Вам следует сохранить этот файл где-нибудь, а когда вам нужно создать документацию, просто откройте его, сохраните его с другим именем в правильном пути и начните копировать ячейки из существующих записных книжек документации.
Это зависит от вас, как высоздать это руководство.А пока давайте просто поставим ерунду.Вы увидите мои скриншоты.Следующие два файла являются документацией для ваших функций.Скопируйте и вставьте файл шаблона в SOPackage/Documentation/English/ReferencePages/Symbols и назовите файлы AddTwo_E.nb и DotTwo_E.nb.Найдите нужную документацию, например, Sin, скопируйте и вставьте информацию в эти файлы.Я изменю имена, чтобы показать, как они работают.
Создание файла шаблона, безусловно, может быть сокращено.Если кто-то знает, как это сделать программно, пожалуйста, не стесняйтесь редактировать этот раздел здесь и заменить его кодом.Вы окажете нам всем огромную услугу.
PacletInfo.m
Этот файл находится прямо в каталоге SOPackage и содержит следующее:
Paclet[
Name -> "SOPackage",
Version -> "0.0.1",
MathematicaVersion -> "8+",
Extensions -> {{
"Documentation",
Resources -> {
"Guides/SOPackage"
},
Language -> "English"
}}
]
Есть одна последняя вещь, которую мы должны сделать, прежде чем мы сможем подготовить документацию.Нам нужно сделать всю документацию по функциям недоступной для редактирования, и мы должны придать ей тот же формат, что и остальным документам.На этот раз я написал сценарий, который делает это.Я называю это MakeDoc, потому что он также создаст индекс.Сохраните этот файл под OSPackage.Я разобью этот файл на две части, чтобы вы могли получить объяснение.
pname = "SOPackage";
Get[pname <> "`"];
basepath = $UserBaseDirectory<>"/Applications/"<>pname<>"/Documentation/English/ReferencePages/Symbols/";
$UserBaseDirectory <> "/Applications/" <> pname <> "/Documentation/English/ReferencePages/Symbols/";
Перед тем, как сделать это, мы должны убедиться, что мы перезапускаем Mathematica.Сначала мы загрузим пакет и установим корневой каталог всей документации по функциям.На следующем шаге мы в основном скопируем код вставки, для каждой функции мы сделаем следующее:
snname := "AddTwo";
nb = NotebookOpen[basepath <> snname <> "_E.nb"];
NotebookSave[nb, basepath <> snname <> ".nb"];
SetOptions[nb,
TaggingRules -> {
"ModificationHighlight" -> False,
"Metadata" -> {
"context" -> pname <> "`",
"keywords" -> {},
"index" -> True,
"label" -> "OSPackage Package Paclet Symbol",
"language" -> "en",
"paclet" -> "OSPackage Package",
"status" -> "",
"summary" -> AddTwo::usage,
"synonyms" -> {},
"title" -> "AddTwo",
"type" -> "Symbol",
"uri" -> pname <> "/ref/AddTwo"},
"SearchTextTranslated" -> ""
}
];
SetOptions[nb, Saveable -> False];
SetOptions[nb,
StyleDefinitions ->
FrontEnd`FileName[{"Wolfram"}, "Reference.nb"]];
NotebookSave[nb];
Этот блок кода открывает документацию редактируемой функции.Сохраняет его с правильным именем.И затем он изменяет свои атрибуты, так что его нельзя редактировать, и он выглядит так же, как и остальные документы.Мы делаем то же самое для каждой функции.Обратите внимание, что для «Summary» установлено сообщение usage функции.Это то, что мы увидим, когда будем искать функцию.
snname := "DotTwo";
nb = NotebookOpen[basepath <> snname <> "_E.nb"];
NotebookSave[nb, basepath <> snname <> ".nb"];
SetOptions[nb,
TaggingRules -> {
"ModificationHighlight" -> False,
"Metadata" -> {
"context" -> pname <> "`",
"keywords" -> {},
"index" -> True,
"label" -> "OSPackage Package Paclet Symbol",
"language" -> "en",
"paclet" -> "OSPackage Package",
"status" -> "",
"summary" -> DotTwo::usage,
"synonyms" -> {},
"title" -> "DotTwo",
"type" -> "Symbol",
"uri" -> pname <> "/ref/DotTwo"},
"SearchTextTranslated" -> ""
}
];
SetOptions[nb, Saveable -> False];
SetOptions[nb,
StyleDefinitions ->
FrontEnd`FileName[{"Wolfram"}, "Reference.nb"]];
NotebookSave[nb];
Очень важно, мы не изменили руководство, это все, что нужно:
snname := "SOPackage";
nb = NotebookOpen[guidepath <> snname <> "_E.nb"];
NotebookSave[nb, guidepath <> snname <> ".nb"];
SetOptions[nb, Saveable -> False];
SetOptions[nb, StyleDefinitions -> FrontEnd`FileName[{"Wolfram"}, "Reference.nb"]];
NotebookSave[nb];
И, наконец,, мы создаем индекс следующим образом:
indir = $UserBaseDirectory<>"/Applications/"<>pname<>"/Documentation/English/Index";
If[FileNames[indir] != {}, DeleteDirectory[indir, DeleteContents -> True]];
ind = DocumentationSearch`NewDocumentationNotebookIndexer[indir];
DocumentationSearch`AddDocumentationNotebook[ind, basepath <> "AddTwo.nb"];
DocumentationSearch`AddDocumentationNotebook[ind, basepath <> "DotTwo.nb"];
DocumentationSearch`CloseDocumentationNotebookIndexer[ind];
Обратите внимание, что нам нужна строка с AddDocumenationNotebook для каждой функции.После запуска MakeDoc.nb будут созданы файлы AddTwo.nb, DotTwo.nb и SOPackage.nb.Эти файлы не могут быть изменены.Вы также увидите папку с именем Index.Это все двоичные данные, которые содержат информацию для док-центра.Если вы когда-либо вносите изменения в документацию, вы должны запустить MakeDoc.nb, чтобы изменения вступили в силу.Вот дерево документов, которое у нас есть сейчас.
После этого мы должны перезапустить Mathematica и взять нашу документацию для поездки.
Это то, что происходит, когдавы ищете "SOPackage".
Давайте посмотрим на использование AddTwo
Обратите внимание, что стрелкасо ссылкой на страницу документа была добавлена автоматически.
К сожалению, если мы ищем AddTwo в центре документов, это то, что мы получаем:
Как мы можем сделать так, чтобы сводка по функции не была отформатирована?
Не стесняйтесь изменять мой код, загрузив его с здесь .
Спасибодля чтения.
Мануэль