wolfram-mathematica - research - wolfram mathematica online

Integración de cuadernos al centro de documentación de Mathematica

Question

Si ha estado usando Mathematica por un tiempo, probablemente se haya unido al centro de documentación. Siempre hay algo nuevo que encuentras en esas páginas. Deja que sean opciones para una función o solo algunos ejemplos que en algún momento no te parecieron útiles.

Es probable que haya escrito paquetes con sus funciones especializadas que usa todo el tiempo. A veces puede pensar en un buen ejemplo para usar con su función, pero es probable que termine siendo olvidado en algún lugar de su disco duro. Si lo hubiera escrito en la documentación en el momento en que lo pensó, tal vez no lo buscaría desesperadamente más adelante.

Por esta razón, me gustaría saber cómo integrar la documentación para sus propias funciones con el centro de documentación de Mathematica mediante programación. Esta pregunta está aquí para explorar cómo adaptar la documentación. Si ha escrito scripts que lo ayudan a hacerlo, compártalo con la comunidad.

Wolfram''s Workbench no es una solución aceptable para esta pregunta. Todo debe hacerse con la instalación simple de Mathematica . Hay un par de puntos que la solución debería cubrir:

1. Crear documentación para una función (preferiblemente una plantilla).
2. Crear guías y tutoriales (si se consideran útiles).
3. Enlazando los cuadernos al centro de documentación.
4. Creando mensajes de "uso" que se visualizan correctamente en diferentes entornos.
   • En el cuaderno de Mathematica ?Symbol
   • En la Search: Symbol Centro de Documentación Search: Symbol

Este es un tema realmente amplio, tengo soluciones para 1, 2 y 3. Me falta el punto número 4. Entonces díganos, ¿cómo documentan sus funciones con el centro de documentación?

Actualizar

He agregado otra respuesta. Esperamos que esta respuesta sea más alentadora para los usuarios de Mathematica para escribir páginas de documentación con sus paquetes. Creo que escribir páginas de documentación es beneficioso tanto para el escritor de la aplicación como para los usuarios de la aplicación. Si descarga el paquete que escribí, le sugiero que siga el tutorial para que pueda ver lo que sucede en cada paso. Esto le dará una valiosa experiencia para proyectos futuros.

Github (24 de mayo de 2014)

Desde que escribí el paquete, ha habido varias personas interesadas en este paquete. He subido el paquete a Github: https://github.com/jmlopez-rod/ApplicationMaker . Por favor, contáctame si deseas colaborar en el repositorio.

Answer 1

He descargado su ApplicationMaker y lo estoy probando usando Mathematica 10 en Windows 7 64 Bit. ¡Buen trabajo y bien documentado! Descubrí un pequeño error que necesitaba una solución en mi configuración al crear una nueva aplicación usando NewApplication . Parece que la root variable en la función MakeDirectory no puede ser una cadena con longitud cero (causa un error al crear los directorios). Lo arreglé incluyendo una prueba en tu código original:

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

Answer 2

Me tomó un tiempo, pero finalmente he terminado de escribir una aplicación documentada de Mathematica para ayudar a los usuarios de Mathematica a escribir sus paquetes documentados.

Esta aplicación se llama ApplicationMaker . Contiene tres paquetes con varias funciones para ayudarlo a crear la aplicación. Al usar estas funciones, puedes omitir todo el lío que describí en mi respuesta anterior.

Si descarga ApplicationMaker de mi sitio web, encontrará un tutorial detallado que le muestra cómo crear una aplicación completa con su documentación.

Visión de conjunto

Para crear una nueva aplicación, comienza llamando a NewApplication . Esto crea el árbol de directorios que mencioné en la respuesta anterior. Para obtener más información sobre la organización de archivos de Mathematica, haga clic here .

El siguiente paso es crear los paquetes. Para eso llamas a NewPackage . Esta función crea una plantilla donde escribe su código.

Cuando termine de escribir su código, debe llamar a UpdateInit . Esto actualiza el archivo de inicio que necesita Mathematica para que pueda usar la función Get (<<) .

En este punto, está listo para crear la documentación. Simplemente llame a CreateReferencePages y esto creará un documento básico que puede editar para documentar las páginas de referencia para cada símbolo en su aplicación.

Si desea crear una guía o un tutorial para su aplicación, puede llamar a NewGuide y NewTutorial .

Cuando termine de hacer sus ediciones, debe construir su aplicación para que Mathematica pueda adaptarla a su centro de documentación. Para ello, llame a BuildApplication .

En este punto has terminado. Si usa Information sobre cualquiera de los símbolos de su paquete, debería ver una flecha adjunta que lo lleva a la página de referencia para ese símbolo.

Si desea compartir esta aplicación, primero debe implementarla. La aplicación actual contiene las páginas de referencia que funcionan con el centro de documentación y las que edita. Al implementarlo, obtiene un directorio con solo los archivos necesarios para que su aplicación funcione.

Instalación

Todo lo que tiene que hacer es soltar la carpeta ApplicationMaker en $UserBaseDirectory/Applications/ o $BaseDirectory/Applications/ .

Para comenzar, abra el centro de documentación y busque "ApplicationMaker". Esto debería mostrarle la guía que muestra todas las funciones que contiene el paquete. En la parte inferior, debería ver un enlace al tutorial.

Ultimas palabras

Esta es la primera aplicación que he desarrollado para Mathematica. Trataré de seguir actualizando el paquete para descubrir nuevas cosas para mejorar el paquete. Por ahora, espero que esta primera versión de ApplicationMaker sea útil para cualquiera que intente documentar sus aplicaciones de Mathematica.

Puede descargar ApplicationMaker https://github.com/jmlopez-rod/ApplicationMaker .

Answer 3

Para mostrar cómo crear documentación que se incorpore al Centro de documentación, crearemos un paquete que contiene funciones muy simples y su documentación. SOPackage nuestro paquete SOPackage . Este paquete se almacenará en una carpeta con el mismo nombre y dicha carpeta se debe almacenar en $BaseDirectory o $UserBaseDirectory$ . La carpeta SOPakage necesita tener la siguiente estructura de árbol.

Observe que la raíz es el directorio SOPackage .

SOPackage

Ahora crearemos un nuevo archivo de cuaderno dentro de SOPackage : SOPackage.nb . Estos son los contenidos del cuaderno

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[];

Aquí hay una captura de pantalla de lo que debería ver

Tenga en cuenta que los mensajes de uso generalmente dan formato a los parámetros de una manera especial. Un atajo para obtener este formato (señalado por @ alexey-popkov) es resaltar la letra que desea formatear, presione Comando + 0 ( Alt + 0 en Windows) e ingrese "TI". Repita este proceso para todas las letras que necesitan ser modificadas. Cambia la celda a una celda de inicialización a través de Cell->CellProperties->Initialization Cell . Ahora guardamos este cuaderno como SOPackage.nb . En caso de que Mathematica no le pregunte si desea crear un paquete porque olvidó cambiar la celda a una celda de inicialización, entonces puede ir a Format->OptionInspector . Asegúrese de estar seleccionando "Opciones para SOPackage.nb"; de lo contrario, la opción que debe establecer en verdadero estará atenuada. Ahora haga clic en Notebook Options->FileOptions->AutoGeneratedPackage y seleccione Automatic . Cierre la ventana de opciones y guarde el archivo. Cada vez que guarde SOPackage.nb el archivo SOPackage.m se actualizará (No se meta con este archivo m).

El directorio Kernel debe contener solo un archivo: init.m Este archivo debe tener la siguiente línea:

Get["SOPackage`SOPackage`"];

Después de esto, tenemos un paquete de trabajo. Puede intentar lo siguiente para asegurarse de que todo funciona correctamente:

<<SOPackage`
?AddTwo
?DotTwo
DotTwo[]
DotTwo[2, 3]

Documentación

Nos permite comenzar creando la página de guía. Esta será la página que se mostrará cuando escriba SOPackage en el centro de documentación. SOPackage/Documentation/English/Guides creando un cuaderno y SOPackage/Documentation/English/Guides en SOPackage/Documentation/English/Guides como SOPackage_E.nb . La razón por la que le doy la extensión "_E" es porque esta será una copia editable. Tenga en cuenta que no puede editar ninguno de los documentos en el centro de documentación. Bueno, puedes, pero estos cambios nunca surten efecto. Probablemente desee modificar su documentación a medida que crea su paquete, por lo que es una buena idea tener una copia que pueda editar. Para este ejemplo, podemos copiar el contenido de la Combinatorica guide , en el centro Doc. Combinatorica/guide/CombinatoricaPackage seleccionar todo con celdas, copiar y pegar en su archivo SOPackage_E.nb (alternativamente, copie el archivo C:/Program Files/Wolfram Research/Mathematica/10.4/Documentation/English/Packages/Combinatorica/Documentation/English/Guides/CombinatoricaPackage.nb o algo equivalente en otros sistemas operativos). Haga algunos cambios solo para que sepa que ellos son los que está haciendo. En mi caso, sustituí Combinatorica con SOPackage. En el caso de que no pueda modificar una parte de un texto, esto es lo que debe hacer:

1: haga clic en el texto que no puede modificar.

2: vaya a la Cell->Show Expression o ingrese Command+Shift+E o algo equivalente en Windows.

3: Busque el segundo argumento en la expresión de Cell (justo antes de cualquier opción de la forma A -> B ). Este es un nombre de estilo. En algunos casos, verá "Uso", "Notas", "Nombre del objeto", entre otros. Una vez que ubicas el estilo de la celda que no puedes modificar, haz clic en el cuaderno que estás editando e ingresa Command+Shift+E para mostrar la expresión.

4: vaya a Format->Edit StyleSheet... estilo Format->Edit StyleSheet... , ingrese el nombre del estilo que vio anteriormente en Enter a style name:

5: aparece una celda que muestra el estilo. Asegúrese de que esta celda esté seleccionada y vaya a Format->Object Inspector . Asegúrese de que dice Show option values selección de Show option values .

6: vaya a Editing Options y establezca Editable en verdadero.

7: Modificar lo inmodificable.

Le sugiero que primero ingrese el nombre de todos los estilos que desea editar, como lo he mostrado en la captura de pantalla. Hasta ahora solo he cambiado los que mencioné en el paso 3. Una vez que los tenga en la lista, selecciónelos todos y configure editable de una vez. Otro punto importante es que este archivo puede ser una plantilla. Deberías guardar este archivo en algún lugar y cuando necesites crear una documentación, simplemente ábrela, guárdala con otro nombre en el camino correcto y comienza a copiar las celdas de los cuadernos de documentación existentes.

Depende de ti cómo creas esta guía. Por ahora vamos a poner tonterías. Verás mis capturas de pantalla. Los siguientes dos archivos son la documentación para sus funciones. Copie y pegue su archivo de plantilla en SOPackage/Documentation/English/ReferencePages/Symbols y nombre los archivos AddTwo_E.nb y DotTwo_E.nb . Busque la documentación que desee, tome Sin por ejemplo, y copie y pegue la información en esos archivos. Cambiaré los nombres solo para mostrar cómo funcionan.

^{La creación del archivo de plantilla seguramente puede reducirse. Si alguien sabe cómo hacer esto mediante programación, no dude en editar esta sección aquí y reemplazarla con el código. Nos harás un gran favor a todos.}

PacletInfo.m

Este archivo se encuentra justo debajo del directorio SOPackage y contiene lo siguiente:

Paclet[
Name -> "SOPackage",
Version -> "0.0.1",
MathematicaVersion -> "8+",
Extensions -> {{
    "Documentation", 
    Resources -> {
        "Guides/SOPackage"
    }, 
    Language -> "English"
}}
]

Hay una última cosa que debemos hacer antes de poder tener preparada la documentación. Necesitamos hacer que toda la documentación de la función no sea editable y tenemos que darle el mismo formato que el resto de los documentos. Esta vez escribí un guión que hace esto. Lo llamo MakeDoc porque también creará el índice. Guarde este archivo en OSPackage . Romperé este archivo en dos partes para que pueda obtener una explicación.

pname = "SOPackage";
Get[pname <> "`"];
basepath = $UserBaseDirectory<>"/Applications/"<>pname<>"/Documentation/English/ReferencePages/Symbols/";
$UserBaseDirectory <> "/Applications/" <> pname <> "/Documentation/English/ReferencePages/Symbols/";

Deberíamos asegurarnos de reiniciar Mathematica antes de hacer esto. Primero cargaremos el paquete y estableceremos el directorio raíz de toda la documentación de la función. En el siguiente paso, básicamente copiaremos un código de pegado, haremos lo siguiente para cada función.

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];

Este bloque de código abre la documentación de la función editable. Lo guarda con el nombre correcto. Y luego cambia sus atributos para que no sea editable y le da el mismo aspecto que el resto de los documentos. Hacemos lo mismo para cada función. Tenga en cuenta que "resumen" está configurado para el mensaje de usage de la función. Esto es lo que veremos cuando busquemos la función.

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];

Muy importante, no hemos modificado la guía, esto es todo lo que se necesita:

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];

Y finalmente, creamos el índice así:

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];

Tenga en cuenta que necesitamos una línea con AddDocumenationNotebook para cada función. Después de ejecutar MakeDoc.nb los archivos AddTwo.nb , DotTwo.nb y SOPackage.nb . Estos archivos no pueden ser modificados. También verá una carpeta llamada Index . Todos estos son datos binarios que contienen información para el centro de documentación. Si alguna vez realiza una modificación en la documentación, debe ejecutar MakeDoc.nb para que los cambios entren en vigencia. Aquí está el árbol de documentos que tenemos ahora.

Después de esto, debemos reiniciar Mathematica y llevar nuestra documentación a dar un paseo.

Esto es lo que sucede cuando buscas "SOPackage".

AddTwo el uso de AddTwo

Observe que una flecha con un enlace a la página del documento se agregó automáticamente.

Desafortunadamente, si buscamos AddTwo en el centro de documentación, esto es lo que obtenemos:

¿Cómo podemos hacerlo para que el resumen de la función no esté formateado?

Siéntase libre de modificar mi código descargándolo desde here .

Gracias por leer.

Manuel