노트북을 Mathematica의 문서 센터에 통합
한동안 Mathematica 를 사용해왔다 면 문서 센터에 애착을 갖게 될 것입니다. 그 페이지에는 항상 새로운 것이 있습니다. 함수에 대한 옵션이거나 어느 시점에서 유용하지 않은 몇 가지 예제로 두십시오.
항상 사용하는 특수 기능으로 패키지를 작성했을 가능성이 큽니다. 때로는 함수와 함께 사용할 깔끔한 예제를 생각할 수 있지만 하드 디스크 어딘가에서 잊혀 질 가능성이 있습니다. 당신이 그것을 생각한 순간 문서에 기록했다면 나중에 필사적으로 그것을 찾지 않을 것입니다.
이런 이유로 저는 Mathematica의 문서 센터와 프로그래밍 방식으로 자신의 함수에 대한 문서를 통합하는 방법을 알고 싶습니다 . 이 질문은 문서를 조정하는 방법을 탐색하기위한 것입니다. 이를 수행하는 데 도움이되는 스크립트를 작성했다면 커뮤니티와 공유하십시오.
Wolfram의 Workbench는이 질문에 적합한 해결책이 아닙니다. Mathematica 의 일반 설치로 모든 작업을 수행해야합니다 . 솔루션이 다루어야 할 몇 가지 사항이 있습니다.
- 함수에 대한 문서 작성 (가급적 템플릿).
- 가이드 및 튜토리얼 만들기 (유용하다고 판단되는 경우).
- 노트북을 문서 센터에 연결.
- 다른 환경에서 올바르게 표시되는 "사용"메시지 생성.
- Mathematica 노트북에서
?Symbol - 문서 센터에서
Search: Symbol
- Mathematica 노트북에서
이것은 정말 광범위한 주제입니다. 1, 2, 3에 대한 솔루션이 있습니다. 4 번을 놓쳤습니다. 문서 센터에서 함수를 어떻게 문서화합니까?
최신 정보
다른 답변을 추가했습니다. 이 답변이 Mathematica 사용자가 패키지와 함께 문서 페이지를 작성하는 데 더 큰 도움이되기를 바랍니다. 문서 페이지를 작성하는 것은 애플리케이션 작성자는 물론 애플리케이션 사용자에게도 유익하다고 생각합니다. 내가 작성한 패키지를 다운로드하면 모든 단계에서 일어나는 일을 볼 수 있도록 튜토리얼을 따르는 것이 좋습니다. 이것은 향후 프로젝트에 대한 귀중한 경험을 제공 할 것입니다.
Github (2014 년 5 월 24 일)
제가 패키지를 작성한 이후로이 패키지에 관심이있는 사람들이 여러 명있었습니다. 패키지를 Github에 업로드했습니다 : https://github.com/jmlopez-rod/ApplicationMaker . 저장소에 기여하고 싶다면 저에게 연락하십시오.
문서 센터에 통합되는 문서를 작성하는 방법을 보여주기 위해 매우 간단한 기능과 문서가 포함 된 패키지를 작성합니다. 패키지를 호출 해 보겠습니다 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. 경우 티카는 당신이 다음에 갈 수 초기화 셀에 셀을 변경하는 것을 잊었다 때문에 패키지를 생성 할 것인지를 물어 보지 않았다 Format->OptionInspector. "Options for 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문서 센터 유형 Combinatorica/guide/CombinatoricaPackage에서 셀이있는 모든 항목을 선택하고 SOPackage_E.nb파일 에 복사하여 붙여 넣을 수 있습니다 (또는 파일 복사C:\Program Files\Wolfram Research\Mathematica\10.4\Documentation\English\Packages\Combinatorica\Documentation\English\Guides\CombinatoricaPackage.nb또는 다른 OS에서 동등한 것). 그들이 당신이 만들고 있다는 것을 알 수 있도록 약간의 변경을하십시오. 제 경우에는 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 :로 가서 true로 Editing Options설정하십시오 Editable.
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문서 센터에서 검색하면 다음과 같은 결과를 얻을 수 있습니다.
How can we make it so that the summary for the function isn't formatted?
Feel free to modify my code by downloading it from here.
Thank you for reading.
Manuel
It took me while but I have finally finished writing a documented Mathematica application to help Mathematica users write their documented packages.
This application is called ApplicationMaker. It contains three packages with various functions to help you create the application. By using these functions you can skip going through all the mess I had described in my previous answer.
If you download ApplicationMaker from my website you will find a detailed tutorial showing you how to create a complete application with its documentation.
Overview
To create a new application you start by calling NewApplication. This creates the directory tree I mentioned in the previous answer. To find more about Mathematica's file organization click here.
The next step is to create the packages. For that you call NewPackage. This function creates a template where you write your code.
When you finish writing your code you need to call UpdateInit. This updates the init file that Mathematica needs so that you can use the function Get (<<).
At this point you are ready to create the documentation. Simply call CreateReferencePages and this will create a basic document that you can edit to document the reference pages for each symbol in your application.
If you want to create a guide or a tutorial for your application then you can call NewGuide and NewTutorial.
When you are done doing your edits you need to build your application so that Mathematica can adapt it to its documentation center. You do this by calling BuildApplication.
At this point you are done. If you use Information on any of the symbols of your package you should see an arrow appended that leads you to the reference page for that symbol.
If you wish to share this application you should first deploy it. The current application contains the reference pages which work with the documentation center and those that you edit. By deploying it you obtain a directory with only the necessary files for your application to work.
Installation
All you have to do is drop the folder ApplicationMaker in $UserBaseDirectory/Applications/ or $BaseDirectory/Applications/.
To get started open up the documentation center and look for "ApplicationMaker". This should show you the guide showing all the functions that the package contains. At the very bottom you should see a link to the tutorial.
Final Words
This is the first application I have ever build for Mathematica. I will try to keep updating the package I as discover new things to make the package better. For now, I hope that this first version of ApplicationMaker is useful to anybody trying to document their Mathematica applications.
You may download ApplicationMaker here.
ApplicationMaker를 다운로드했으며 Windows 7 64 비트에서 Mathematica 10을 사용하여 테스트 중입니다. 훌륭하고 잘 문서화되었습니다! .NET을 사용하여 새 응용 프로그램을 만들 때 설정을 수정해야하는 작은 오류를 발견했습니다 NewApplication. root함수 의 변수 는 MakeDirectory길이가 0 인 문자열이 될 수없는 것 같습니다 (디렉터리 생성시 오류 발생). 원래 코드에 테스트를 포함하여이 문제를 해결했습니다.
MakeDirectory[root_, start_, main_, sub_] := Module[
{nm, ns, tmp},
nm = Position[main, start];
If[Length@nm != 0, nm = nm[[1, 1]]];
If[Length@sub[[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, Length@sub[[nm]]}]
];
Do[
MakeDirectory[
If[StringLength[root] != 0, FileNameJoin[{root, start}], start],
sub[[nm, i]], main, sub],
{i, Length@sub[[nm]]}
]
]
'IT박스' 카테고리의 다른 글
| CSS 성능 프로파일 러? (0) | 2021.01.08 |
|---|---|
| Ruby on Rails 3.1 및 jQuery UI 이미지 (0) | 2021.01.08 |
| 오류 : Express에서보기를 조회하지 못했습니다. (0) | 2021.01.08 |
| webdriver에서 요소의 현재 내용을 어떻게 얻을 수 있습니까? (0) | 2021.01.08 |
| 트리거가 테이블에있을 때 OUTPUT 절과 함께 UPDATE를 사용할 수 없습니다. (0) | 2021.01.08 |