Completed documentation of ForScience`PacletUtils

Added doc page for DocumentationBuilder Added doc page for DocumentationHeader Added doc page for Details Added doc page for Examples Added doc page for SeeAslo
MMA-ForScience · May 10, 2018 · 1562c2d · 1562c2d
1 parent 392ba6c
commit 1562c2d
Show file tree

Hide file tree

Showing 13 changed files with 906 additions and 11 deletions.
diff --git a/ForScience/PacletInfo.m b/ForScience/PacletInfo.m
@@ -4,7 +4,7 @@
   Name -> "ForScience",
   Description -> "Contains various utility functions and styling to make it easier to use MMA for scientific plots",
   Creator -> "Lukas Lang & Marc Lehner",
-  Version -> "0.63.7",
+  Version -> "0.63.8",
   MathematicaVersion -> "11.1+",
   Extensions -> {
     { "Documentation", Language -> "English"},

diff --git a/ForScience/PacletUtils.wl b/ForScience/PacletUtils.wl
@@ -40,6 +40,11 @@ BeginPackage["ForScience`PacletUtils`",{"PacletManager`","JLink`","Documentation
 <<`ProcessFileDoc`;
 <<`BuildPacletDoc`;
 <<`BuildActionDoc`;
+<<`DocumentationBuilderDoc`;
+<<`DocumentationHeaderDoc`;
+<<`DetailsDoc`;
+<<`ExamplesDoc`;
+<<`SeeAlsoDoc`;
 
 
 EndPackage[]
diff --git a/ForScience/PacletUtils/Details.wl b/ForScience/PacletUtils/Details.wl
@@ -1,7 +1,6 @@
 (* ::Package:: *)
 
-Details::usage=FormatUsage@"";
-FormatTable::usage=FormatUsage@"FormatTable handles the formatting of [*TableForm*] expressions in documentation pages.";
+Details;
 
 
 Begin["`Private`"]
@@ -191,6 +190,8 @@ MakeDetailsSection[sym_,nb_,OptionsPattern[]]:=
           Cell[BoxesToDocEntry@ParseFormatting@FormatUsageCase@#,"Notes"],
           _TableForm,
           FormatTable@#,
+          _Cell,
+          #,
           _BoxData,
           Cell@#,
           _,

diff --git a/ForScience/PacletUtils/DetailsDoc.wl b/ForScience/PacletUtils/DetailsDoc.wl
@@ -0,0 +1,115 @@
+(* ::Package:: *)
+
+Usage[Details]="[*[*Details[sym]*]'''={```note```_1,\[Ellipsis]}'''*] sets the content of the \"Details and Options\" section in documentation pages generated by [*DocumentationBuilder*].";
+
+
+BuildAction[
+
+
+DocumentationHeader[Details]=FSHeader["0.57.0","0.61.8"];
+
+
+Details[Details]={
+  "[*Details*] is one of the metadata symbols used by [*DocumentationBuilder*]. Others include [*Usage*], [*Examples*] and [*SeeAlso*].",
+  "The generated section includes the proper thumbnail.",
+  "The value of [*Details[sym]*] is attached to ```sym``` as an upvalue.",
+  "[*Details[sym]*] needs to be set to a list of notes. Possible types of notes are:",
+  TableForm@{
+    {"\"```note```\"","A string, to be formatted by [*ParseFormatting*]"},
+    {"TableForm[\[Ellipsis]]","A table with the specified contents"},
+    {"Cell[\[Ellipsis]]","A cell, to be inserted exactly as-is"},
+    {"BoxData[\[Ellipsis]]","A custom cell with the specied [*BoxData*] content"},
+    {"```expr```","Any expression, to be converted to boxes by [*ToBoxes*]"}
+  },
+  "In formatted strings, symbols wrapped in [\[InvisibleSpace]*\[Ellipsis]*\[InvisibleSpace]] are converted into hyperlinks if they are documented.",
+  "Tables can have 2 or 3 columns. Possible types of entries are:",
+  TableForm@{
+    {"\"```text```\"","A string, to be formatted by [*ParseFormatting*]"},
+    {"```symbol```","A symbol, to be hyperlinked if it is documented"},
+    {"Cell[\[Ellipsis]]","A cell, to be inserted exactly as-is"},
+    {"BoxData[\[Ellipsis]]","A custom cell with the specied [*BoxData*] content"},
+    {"```expr```","Any expression, to be converted to boxes by [*ToBoxes*]"}    
+  }
+};
+
+
+Examples[Details,"Basic examples"]={
+  {
+    "Load the ForScience package:",
+    ExampleInput[Needs["ForScience`PacletUtils`"]],
+    "Create a symbol to build a documentation page for:",
+    ExampleInput[
+      DocumentationHeader[test]={"TEST SYMBOL",Blue,"Introduced in the documentation"};,
+      InitializationCell->True
+    ],
+    "Attach [*Details*] information to the symbol:",
+    ExampleInput[
+      "Details[test]={
+        \"This is some text\",
+        \"```Formatting``` works '''too'''.\"
+      };",
+      DocumentationBuilder[test]
+    ],
+    ExampleInput[NotebookClose[%];,Visible->False]
+  },
+  {
+    "Hyperlinks are generated for symbols wrapped in [\[InvisibleSpace]*\[Ellipsis]*\[InvisibleSpace]]:",
+    ExampleInput[
+      "Details[test]={
+        \"Hyperlinks for symbols: [*DocumentationBuilder*], [*Details*]\",
+        \"Hyperlinks is usages: [*Details[foo]*]\",
+        \"Undocumented functions do not get hyperlinked: [*UnknownSymbol*]\"
+      };",
+      DocumentationBuilder[test]
+    ],
+    ExampleInput[NotebookClose[%];,Visible->False]
+  },
+  {
+    "Tables can also be added to the details section:",
+    ExampleInput[
+      "Details[test]={
+        \"The following is a table:\",
+        TableForm@{
+          {\"Some text\",\"'''Formatted text'''\"},
+          {\"A symbol\",Automatic}
+        }
+      };",
+      DocumentationBuilder[test]
+    ],
+    ExampleInput[NotebookClose[%];,Visible->False]
+  },
+  {
+    "3-column tables are also supported:",
+    ExampleInput[
+      "Details[test]={
+        \"The following is a table:\",
+        TableForm@{
+          {\"This table\",\"has\",\"three columns\"},
+          {\"Hyperlinks in text:\",\"This is a link: [*List*]\",\"Usage case: [*Usage[sym]*]\"}
+        }
+      };",
+      DocumentationBuilder[test]
+    ],
+    ExampleInput[NotebookClose[%];,Visible->False]
+  }
+};
+
+
+Examples[Details,"Properties & Relations"]={
+  {
+  "Generation of the \"Details and Options\" section can be disabled using the option [*Details->False*]:",
+    ExampleInput[
+      "Details[test]={
+        \"Some important details\"
+      };",
+      DocumentationBuilder[test,Details->False]
+    ],
+    ExampleInput[NotebookClose[%];,Visible->False]
+  }
+};
+
+
+SeeAlso[Details]={DocumentationBuilder,Usage,Examples,SeeAlso};
+
+
+]
diff --git a/ForScience/PacletUtils/DocumentationBuilder.wl b/ForScience/PacletUtils/DocumentationBuilder.wl
@@ -1,7 +1,6 @@
 (* ::Package:: *)
 
-DocumentationBuilder::usage=FormatUsage@"DocumentationBuilder is a global postprocessor for [*BuildPaclet*], that builds documentation pages for any symbols with [*DocumentationHeader*] set.
-DocumentationBuilder[sym] builds and displays the documentation page for the specified symbol. The return value is a reference to that notebook.";
+DocumentationBuilder;
 
 
 Begin["`Private`"]

diff --git a/ForScience/PacletUtils/DocumentationBuilderDoc.wl b/ForScience/PacletUtils/DocumentationBuilderDoc.wl
@@ -0,0 +1,141 @@
+(* ::Package:: *)
+
+Usage[DocumentationBuilder]="DocumentationBuilder is a global postprocessor for [*BuildPaclet*], that builds documentation pages for any symbols with [*DocumentationHeader*] set.
+DocumentationBuilder[sym] builds and displays the documentation page for the specified symbol. The return value is a reference to that notebook.";
+
+
+BuildAction[
+
+
+DocumentationHeader[DocumentationBuilder]=FSHeader["0.55.0","0.61.8"];
+
+
+Details[DocumentationBuilder]={
+  "[*DocumentationBuilder*] is designed to be used as a global post processor of [*BuildPaclet*].",
+  "[*DocumentationBuilder*] generates documentation pages in the exact same style as the official Mathematica documentation.",
+  "[*DocumentationBuilder*] generates search indexes for the documentation for both pre 11.2 and post 11.2 versions of Mathematica.",
+  "The resulting documentation pages are cached and only rebuilt when necessary.",
+  "Currently, only symbol reference pages are supported.",
+  "[*DocumentationBuilder[sym]*] can be used to manually build the documentation page for a single symbol. The resulting page is directly displayed and the [*Notebook[\[Ellipsis]]*] object is returned.",
+  "[*DocumentationBuilder*] can only build documentation pages for symbols with [*DocumentationHeader[sym]*] set.",
+  "[*DocumentationBuilder*] accepts the following options:",
+  TableForm@{
+    {"\"CacheDirectory\"","\"cache\"","The directory to store cached documentation pages and search indices"},
+    {Usage,True,"Whether to generate the usage section"},
+    {Details,True,"Whether to generate the details section"},
+    {Examples,True,"Whether to generate the examples section"}
+  },
+  "Data for symbol reference pages are attached to the symbol to be documented (e.g. [*Usage[sym]*]'''=```usage```''').",
+  "The following data are used to build symbol reference pages:",
+  TableForm@{
+    {"[*Usage[sym]*]","Usage cases for the symbol. [*Usage[sym]*] These are also used to generate the summary seen in the search results page."},
+    {"[*Details[sym]*]","Contents of the \"Details and Options\" section"},
+    {"[*Examples[sym,\[Ellipsis]]*]","Contents of the \"Examples\" section"},
+    {"[*SeeAlso[sym]*]","Related symbols that appear in the \"See Also\" section and at the top in the dropdown."}
+  },
+  "The complete documentation of the ForScience package is generated using [*DocumentationBuilder*]."
+};
+
+
+Examples[DocumentationBuilder,"Basic examples"]={
+  {
+    "Load the ForScience package:",
+    ExampleInput[Needs["ForScience`PacletUtils`"]],
+    "Setup an empty documentation page for a symbol:",
+    ExampleInput[
+      DocumentationHeader[foo]={"EXAMPLE SYMBOL",Gray,"Never introduced."};
+      nb=DocumentationBuilder[foo];,
+      InitializationCell->True
+    ]
+  },
+  {
+    "Close the page and add a usage section:",
+    ExampleInput[
+      NotebookClose[nb];,
+      Usage[foo]="foo[a,b] does something.";,
+      nb=DocumentationBuilder[foo];
+    ]
+  },
+  {
+    "Add some details:",
+    ExampleInput[
+      NotebookClose[nb];,
+      Details[foo]={"[*foo*] does great things if applied correctly."};,
+      nb=DocumentationBuilder[foo];
+    ]
+  },
+  {
+    "Add an example:",
+    ExampleInput[
+      NotebookClose[nb];,
+      Examples[foo,"Basic examples"]={{"Use [*foo*] for something cool:",ExampleInput[foo[a,b]]}};,
+      nb=DocumentationBuilder[foo];
+    ]
+  },
+  {
+    "Add links to related symbols:",
+    ExampleInput[
+      NotebookClose[nb];,
+      SeeAlso[foo]={List,Set};,
+      nb=DocumentationBuilder[foo];
+    ]
+  }
+};
+
+
+Examples[DocumentationBuilder,"Options","Usage"]={
+  {
+    "By default, all sections of the documentation page are built:",
+    ExampleInput[
+      NotebookClose[nb];,
+      Usage[foo]="foo[a,b] does something.";,
+      nb=DocumentationBuilder[foo];
+    ],
+    "Disable the usage section to speed up the build:",
+    ExampleInput[
+      NotebookClose[nb];,
+      nb=DocumentationBuilder[foo,Usage->False];
+    ]
+  }
+};
+
+
+Examples[DocumentationBuilder,"Options","Details"]={
+  {
+    "By default, all sections of the documentation page are built:",
+    ExampleInput[
+      NotebookClose[nb];,
+      Details[foo]={"[*foo*] does great things if applied correctly."};,
+      nb=DocumentationBuilder[foo];
+    ],
+    "Disable the details section to speed up the build:",
+    ExampleInput[
+      NotebookClose[nb];,
+      nb=DocumentationBuilder[foo,Details->False];
+    ]
+  }
+};
+
+
+Examples[DocumentationBuilder,"Options","Examples"]={
+  {
+    "By default, all sections of the documentation page are built:",
+    ExampleInput[
+      NotebookClose[nb];,
+      Examples[foo,"Basic examples"]={{"Use [*foo*] for something cool:",ExampleInput[foo[a,b]]}};,
+      nb=DocumentationBuilder[foo];
+    ],
+    "Disable the example section to speed up the build:",
+    ExampleInput[
+      NotebookClose[nb];,
+      nb=DocumentationBuilder[foo,Examples->False];
+    ],
+    ExampleInput[NotebookClose[nb];,Visible->False]
+  }
+};
+
+
+SeeAlso[DocumentationBuilder]={DocumentationHeader,BuildPaclet,Usage,Details,Examples,SeeAlso};
+
+
+]
diff --git a/ForScience/PacletUtils/DocumentationHeader.wl b/ForScience/PacletUtils/DocumentationHeader.wl
@@ -1,7 +1,7 @@
 (* ::Package:: *)
 
-DocumentationHeader::usage=FormatUsage@"DocumentationHeader[sym]'''={```header```,```color```,```footer```}''' sets the header text, header color and footer message for the documentation pages built by [*DocumentationBuilder*].";
-$ForScienceColor::usage=FormatUsage@"$ForScienceColor is the documentation header color used by the ForScience package.";
+DocumentationHeader;
+$ForScienceColor;
 
 
 Begin["`Private`"]

diff --git a/ForScience/PacletUtils/DocumentationHeaderDoc.wl b/ForScience/PacletUtils/DocumentationHeaderDoc.wl
@@ -0,0 +1,68 @@
+(* ::Package:: *)
+
+Usage[DocumentationHeader]="[*[*DocumentationHeader[sym]*]'''={```header```,```color```,```footer```}'''*] sets the header text, header color and footer message for the documentation pages built by [*DocumentationBuilder*].";
+Usage[$ForScienceColor]="$ForScienceColor is the documentation header color used by the ForScience package.";
+
+
+BuildAction[
+
+
+DocumentationHeader[DocumentationHeader]=FSHeader["0.55.0","0.61.8"];
+
+
+Details[DocumentationHeader]={
+  "[*DocumentationHeader*] is the metadata handler for the basic data needed by [*DocumentationBuilder*] to build a documentation page.",
+  "[*DocumentationBuilder*] can build a documentation page if and only if the corresponding [*DocumentationHeader*] is set.",
+  "[*DocumentationHeader[sym]*] needs to be set to a list with the following three entries:",
+  TableForm@{
+    {"```header```","The header text, describing the type of documentation page"},
+    {"```color```","The color of the header bar"},
+    {"```footer```","The content of the footer of the documentaion page, containg introduction and modification dates."}
+  },
+  "In the footer text, version numbers of the form #.#.# automatically formatted as such.",
+  "[*DocumentationHeader[sym]*] can be removed with [*DocumentationHeader[sym]*]'''=.'''"
+};
+
+
+Examples[DocumentationHeader,"Basic examples"]={
+  {
+    "Load the ForScience package:",
+    ExampleInput[Needs["ForScience`PacletUtils`"]],
+    "Create an empty documentation page with the specified coloring and text:",
+    ExampleInput[
+      DocumentationHeader[foo]={"MY FANCY DOCUMENTATION",Magenta,"This is was introduced in 0.0.0"};
+      DocumentationBuilder[foo]
+    ],
+    ExampleInput[NotebookClose[%];DocumentationHeader[foo]=.,Visible->False]
+  }
+};
+
+
+Examples[DocumentationHeader,"Properties & Relations"]={
+  {
+    "Documentation pages can only be generated for symbols with [*DocumentationHeader*] set:",
+    ExampleInput[Clear@bar,Visible->False],
+    ExampleInput[
+      Usage[bar]="bar[a] is doing absolutely nothing.";,
+      DocumentationBuilder[bar]
+    ],
+    "Set [*DocumentationHeader[bar]*] to enable building the page:",
+    ExampleInput[
+      DocumentationHeader[bar]={"GREAT SYMBOL",Black,"Now it works."};,
+      DocumentationBuilder[bar]
+    ],
+    ExampleInput[NotebookClose[%];DocumentationHeader[bar]=.,Visible->False]
+  }
+};
+
+
+SeeAlso[DocumentationHeader]=Hold[DocumentationBuilder,$ForScienceColor,Usage,Details,Examples,SeeAlso];
+
+
+DocumentationHeader[$ForScienceColor]=FSHeader["0.55.0"];
+
+
+SeeAlso[$ForScienceColor]={DocumentationHeader,DocumentationBuilder};
+
+
+]