Wolfram Language Paclet Repository
Community-contributed installable additions to the Wolfram Language
Wolfram Language Paclet Repository Guidelines
Wolfram Language Paclet Repository Guidelines
Requirements, best practices and suggestions for developing paclets for publication in the repository
More Information
More Information
The following resources contain more helpful information on creating paclets, including examples.
◼
Paclets guide page
◼
Creating Paclets tutorial
◼
Paclet Tools guide page
◼
Definition Notebook
Definition Notebook
◼
Paclets must be published to the repository using a paclet resource definition notebook.
◼
Definition notebooks should be competed with all fields filled.
◼
The definition notebook’s Check button must be used and the discovered errors resolved before a paclet can be published in the repository.
◼
It is common practice to save the definition notebook as ResourceDefinition.nb in your paclet source beside the PacletInfo file.
Environment
Environment
◼
Developing paclets for the repository requires a desktop Wolfram Language environment of Version 13.0 or higher.
Publisher ID-Based Names
Publisher ID-Based Names
To prevent conflicts and confusion, names in the paclet repository are based on publisher IDs.
◼
Paclet names must have the form “PublisherID/PacletBaseName”.
◼
Symbols declared by the paclet must be in the context “PublisherID`”.
◼
Symbols intended for users should be in the context “PublisherID`PacletBaseName`”.
◼
Private symbols not intended for users are commonly defined in deeper contexts like “PublisherID`PacletBaseName`Internal`”.
◼
All stylesheets and palettes must be stored in subdirectories of the StyleSheets and Palettes directory.
◼
The stylesheet and palette subdirectory name should be either the PublisherID or PacletBaseName. For example, a typical stylesheet path within a paclet will be FrontEnd/StyleSheets/PacletBaseName/MyStyleSheet.nb or FrontEnd/StyleSheets/PublisherID/MyStyleSheet.nb.
Documentation
Documentation
Every user-level feature of a paclet should be documented. From the definition notebook toolbar, you can access the Documentation Tools palette.
Symbol Documentation
Symbol Documentation
Every symbol intended for users should have a dedicated documentation page.
Usage
Usage
◼
Function documentation pages should have usage statements for each supported input syntax.
◼
Each usage (including the input pattern and text) should form a sentence and end with a period.
◼
Symbols and variable names should be templated by highlighting the text and using the Template Input button in the Tools menu
◼
Options and their possible values should be specified in the "Details & Options" section. If your function accepts options, they are already implied in the usage.
See examples
Details & Options
Details & Options
◼
◼
Options should be documented using a three-column table with no header row. The first column should be the option name, the second column the default value and the third column a brief description.
See examples
◼
Option names that are already documented as built-in options should be linked to their respective documentation pages using the Template Input button.
See examples
◼
Strings should be denoted with straight quotes (") and not curly quotes (“, ”).
See examples
Examples
Examples
◼
Basic usage scenarios should be demonstrated using clear, runnable examples with reproducible output.
◼
Within an example section, multiple examples should be separated by delimiters.
◼
Example separated by delimiters or sections headers must work independently. Later examples cannot depend on variables defined in earlier examples.
◼
Each example should start with a text description ending in a colon.
◼
Captions should be very brief (typically no more than one sentence).
◼
The first “Basic Example” should be the simplest use case of the symbol.
◼
The “Scope” examples should show the breadth of the function including at least one example of each of the documented input patterns.
◼
Complicated examples containing long inputs or many steps should be included in the “Applications” or “Neat Examples” sections.
Guide Pages
Guide Pages
◼
The paclet should contain at least one guide page that can serve as the main guide page on the paclet homepage. The main guide page should include the most commonly used features of the paclet.
◼
The text at the top of the guide page beneath the title should provide context for rest of the page. It should be a few sentences long.
◼
Entries created with the 1 Line Function Listing button should contain a very brief phrase describing the symbol in the context of the guide page. The same symbol can have different descriptions on different guide pages.
◼
The body of the guide page should primarily contain lists of linked symbols. Text should be limited and examples should not be included.
License
License
◼
Paclets must contain licensing information. If no license is chosen in the definition notebook, a default will be assigned.
◼
The licenses listed in the definition notebook are recommended.
Paclet Configuration
Paclet Configuration
◼
Autoloading paclets that set Loading Automatic in the PacletInfo file must also set HiddenImportTrue.
◼
Autoupdating paclets that set Updating Automatic in the PacletInfo file are prohibited.
Paclet Operations
Paclet Operations
◼
Modifying protected symbols in the System` context is prohibited.
◼
Modifying unprotected symbols in the System` context (for example, $CloudBase) must be clear to the user.
◼
Creating new symbols outside of the dedicated PublisherID` context is prohibited.
◼
All operations that have effects external to the operation of the paclet should be noted in the "Disclosures" section of the definition notebook.