Интеграция ноутбуков в центр документации Mathematica

Ответ 1

Мне потребовалось время, но я, наконец, закончил писать документированное приложение Mathematica, чтобы помочь пользователям Mathematica записывать свои документированные пакеты.

Это приложение называется ApplicationMaker. Он содержит три пакета с различными функциями, которые помогут вам создать приложение. Используя эти функции, вы можете пропустить весь беспорядок, который я описал в своем предыдущем ответе.

Если вы загрузите ApplicationMaker с моего сайта, вы найдете подробный учебник, в котором рассказывается, как создать полное приложение с его документацией.

Обзор

Чтобы создать новое приложение, вы начинаете с вызова NewApplication. Это создает дерево каталогов, о котором я упоминал в предыдущем ответе. Чтобы узнать больше о организации файлов Mathematica, нажмите здесь.

Следующий шаг - создать пакеты. Для этого вы вызываете NewPackage. Эта функция создает шаблон, в котором вы пишете свой код.

Когда вы закончите писать код, вам нужно позвонить UpdateInit. Это обновляет файл инициализации, который требуется Mathematica, чтобы вы могли использовать функцию Get (<<).

На этом этапе вы готовы создать документацию. Просто позвоните CreateReferencePages, и это создаст базовый документ, который вы можете редактировать для документирования ссылочных страниц для каждого символа в вашем приложении.

Если вы хотите создать руководство или учебное пособие для своего приложения, вы можете вызвать NewGuide и NewTutorial.

Когда вы закончите редактирование, вам необходимо создать приложение, чтобы Mathematica могла адаптировать его к своему центру документации. Вы делаете это, вызывая BuildApplication.

На этом мы закончили. Если вы используете Information для любого из символов вашего пакета, вы должны увидеть прилагаемую стрелку, которая приведет вас к ссылочной странице для этого символа.

Если вы хотите поделиться этим приложением, вы должны сначала его развернуть. Текущее приложение содержит справочные страницы, которые работают с центром документации и теми, которые вы редактируете. Развернув его, вы получите каталог с только необходимыми файлами для работы вашего приложения.

Установка

Все, что вам нужно сделать, это отбросить папку ApplicationMaker в $UserBaseDirectory/Applications/ или $BaseDirectory/Applications/.

Для начала откройте центр документации и найдите "ApplicationMaker". Это должно показать вам руководство, показывающее все функции, которые содержит пакет. В самом низу вы должны увидеть ссылку на учебник.

Заключительные слова

Это первое приложение, которое я когда-либо создавал для Mathematica. Я постараюсь продолжать обновление пакета. Я обнаруживаю новые вещи, чтобы сделать пакет лучше. На данный момент я надеюсь, что эта первая версия ApplicationMaker полезна всем, кто пытается документировать свои приложения Mathematica.

Вы можете скачать ApplicationMaker здесь.

Ответ 2

Чтобы показать, как создавать документацию, которая входит в Центр документации, мы создадим пакет, содержащий очень простые функции и документацию. Позвоните в наш пакет 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 или что-то подобное в окнах.

3: Ищите второй аргумент в выражении Cell (прямо перед любыми параметрами формы A -> B). Это имя стиля. В некоторых случаях вы увидите "Использование", "Заметки", "Имя объекта" и другие. После определения стиля ячейки, которую вы не можете изменить, нажмите на редактируемый блокнот и введите Command+Shift+E, чтобы отобразить выражение.

4: перейдите к Format->Edit StyleSheet..., введите имя стиля, которое вы видели ранее в Enter a style name:.

5: Появится ячейка, показывающая стиль. Убедитесь, что эта ячейка выбрана и перейдите к Format->Object Inspector. Убедитесь, что он говорит Show option values Selection.

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"
}}
]

Есть одна последняя вещь, которую мы должны сделать, прежде чем мы сможем подготовить документацию. Нам нужно сделать всю документацию по функциям неотредактированной, и мы должны предоставить ей тот же формат, что и остальные документы. На этот раз я написал script, который делает это. Я называю это MakeDoc, потому что он также будет создавать индекс. Сохраните этот файл под OSPackage. Я разорву этот файл на 4 части, чтобы вы могли получить объяснение.

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 в центре документа, это то, что мы получаем:

<Т411 >

Как мы можем сделать так, чтобы сводка для функции не отформатировалась?

Не стесняйтесь модифицировать мой код, загрузив его из здесь.

Спасибо, что прочитали.

Мануэль

Ответ 3

Я загрузил ваш ApplicationMaker и тестировал его с помощью Mathematica 10 в Windows 7 64 Bit. Отличная работа и хорошо документирована! Я обнаружил небольшую ошибку, которая потребовала исправления при настройке при создании нового приложения с помощью NewApplication. Похоже, что переменная root в функции MakeDirectory не может быть строкой с нулевой длиной (вызывает ошибку при создании каталогов). Я исправил это, включив тест в ваш исходный код:

MakeDirectory[root_, start_, main_, sub_] := Module[
  {nm, ns, tmp},
  nm = Position[main, start];
  If[[email protected] != 0, nm = nm[[1, 1]]];
  If[[email protected][[nm]] != 0,
   Do[
    tmp = 
     If[StringLength[root] != 0, 
      FileNameJoin[{root, start, sub[[nm, i]]}], 
      FileNameJoin[{start, sub[[nm, i]]}]];
    If[DirectoryQ[tmp], 
     Print[Style["Existing Directory : ", "MSG", Gray], 
      Style[tmp, "MSG", Bold]], 
     CreateDirectory[tmp];
     Print[Style["Directory Created  : ", "MSG", Blue], 
      Style[tmp, "MSG", Bold]]
     ];
    , {i, [email protected][[nm]]}]
   ];
  Do[
   MakeDirectory[
    If[StringLength[root] != 0, FileNameJoin[{root, start}], start], 
    sub[[nm, i]], main, sub],
   {i, [email protected][[nm]]}
   ]
  ]