Code Project Generation
DocFX requires "proper" C# project file(s) that references the package source code files and the correct compiled code libraries in order to generate the Script Reference with links to types defined outside of the current package. This allows, for example, DocFX to create a link from a graphics package API using Texture to the core Unity Script Reference. Without a proper project file, DocFX, just puts in the bare type name with no link and no namespace. Readers have no way to know where a given type came from and no easy way to navigate to more docs about that type.
The Package Manager Doc Tools (PMDT) relies on the running Unity Editor to provide the context for defining which version of the Unity libraries to reference in the project. For example, if the running Editor is version 2020.3, then only types available in 2020.3 can be linked. The destination of the links is determined by the xrefmap resolution step.
PMDT passes the assembly-specific code project files generated by an IDE support package built into Unity for DocFX to analyse and extract API documentation. Your Unity Preferences must be set such that Unity generates the necessary project files.
Note
The option to have the PMDT create a CS project file that included all the source code files it could find is no longer available. Earlier versions of this document called this obsolete option, "monolithic generation."
CS project generation
CS project generation requires the use of a built-in IDE support package, which require their matching IDE to be installed, and global Editor preferences to be configured.
There are two currently supported IDE support packages tested with this method:
Built-in .csproj generation must be enabled in the External Tools sub menu in Unity's User Preferences:
PMDT attempts to locate a generated .csproj file for each Assembly Definition included in the package and an additional Player.csproj file for each assembly if Generate .csproj files for: ... Player projects is enabled in User Preferences. Each matching .csproj file is copied to a temporary directory and listed in the generated DocFX config file metadata section.
Preprocessor directives
.csproj files generated by the supported IDE support packages contain Unity version-specific and assembly-specific preprocessor directives, for example a file Unity.RenderPipelines.HighDefinition.Editor.csproj generated by Unity 2021.3 for HD Render Pipeline will include among others the following preprocessor symbols:
UNITY_2021_3_OR_NEWERUNITY_EDITOR
PMDT adds PACKAGE_DOCS_GENERATION and any additional symbols from DefineConstants in Documentation~/config.json. Further information.
Another project file is also generated by HD Render Pipeline for its runtime assembly Unity.RenderPipelines.HighDefinition.Runtime.csproj. This also includes a UNITY_2021_3_OR_NEWER preprocessor but deliberately does not include UNITY_EDITOR. If Player projects is enabled in User Preferences - External Tools an additional project is created Unity.RenderPipelines.HighDefinition.Runtime.Player.csproj.
It is common in package code to conditionally compile API definitions using the UNITY_EDITOR directive in source files that are common to Editor and Runtime assemblies. Both Editor and Runtime .csproj files are submitted to DocFX for code analysis, one of which includes UNITY_EDITOR. The resulting documentation is more complete by default without editing the package source code to add PACKAGE_DOCS_GENERATION to conditional statements, or to specify UNITY_EDITOR in DefineConstants inside Documentation~/config.json.
These preprocessor constants reflect the context in which Unity built the target package source code and its dependencies.