Generate documentation

Use the Package Manager Documentation Tools (PMDT) window to generate a copy of a package's documentation locally. You can also use the window to check for documentation and API errors, and prepare documentation for offline usage.

Prerequisites

Important

Starting from PMDT 3.0.0 DocFX isn't included and must be installed as a dotnet tool. For more information, refer to Installing DocFX.

Update button
The Package Manager Window with the PMDT package installed

Generating documentation

To generate the documentation:

  1. Open the Package Manager window (Window > Package Manager).
  2. Select the package you want to generate documentation for in the Packages list.
  3. Select Generate Documentation.

PMDT then uses DocFX to build the documentation on your local machine. It then opens an Explorer or Finder window to a folder that contains the website files.

Find and view errors

Once you've generated the documentation for a package, you can select View Error Report to check errors and warnings emitted by DocFX or the Package validation tool. This contains information such as:

  • Broken or missing links
  • Broken syntax

Use a different design theme

You can use a different theme from the default to adjust the design of the generated documentation. To select a different theme, choose a Theme option before you generate the documentation.

Important

Modern Theme selection isn't available in Unity 2020.3 or 2019.4. In these versions of Unity PMDT uses the Unity Classic theme and presents the Build offline docs checkbox to enable Unity Classic + Offline.

Unity Classic is a customized DocFX default theme with some UX improvements and support for Unity's language switcher, version switcher and feedback submission widgets.

Unity Classic + Offline is Unity Classic plus the DocFX statictoc template. Select this theme to build a docs website with a static table of contents, suitable for viewing in a browser without a local server.

Modern is DocFX's new production template which enables new features including dark mode, Math expressions and Mermaid diagrams. It doesn't include Unity's language switcher, version switcher, feedback widget, or UX improvements and isn't production-ready. It's included for early testing only.

Output directories

Report output directories

Reports are written relative to the root of the project that PMDT is installed into:

File Output path
Full validation report <project root>/Logs/DocToolReports/<package name@version>.txt

Documentation output directories

The package documentation is written to the persistent data path for the Editor. The appropriate folder is opened when the documentation generation completes:

File Output path
Package and offline documentation <persistent data path>/../../unity/editor/documentation/packages/<package name@version>
Zipped documentation <persistent data path>/../../unity/editor/documentation/zips/<language code + cryptographic hash>.zip
API metadata <persistent data path>/../../unity/editor/documentation/api-metadata/<package name@version>

You can set a different path in the Output Path field in the Package Manager window before generating the documentation. To restore the default path, delete the contents of the field.

View the generated documentation

By default, you must view the generated documentation on a web server. This is because of the way the web page code is set up in DocFX. You have the following options to view the documentation you have just generated:

  • Select a theme with + Offline before generating. This option uses different web page code that can be viewed by opening the pages directly from the file system in your web browser. However, the pages are larger and the code is a little slower.
  • Use a localhost web server to serve the pages.
Tip

Use Python to run a local host server by running python -m http.server 8080 in a command line or terminal. For example, you can run the following commands in a batch file on Windows to start a server and open the Chrome browser:

pushd "d:\docs" 
start chrome http://localhost:8080
python -m http.server 8080
popd

(replacing d:\docs with the path at which you generate your docs.)

Additional resources