What is the exact behaviour of "View..." links?

Unity Engine
1

From experimenting, the following PacMan links/buttons seem to do:

  • View documentation => Open the first file (?) under Documentation~/
  • View changelog => Open CHANGELOG.md
  • View licenses => Open LICENSE.md

Is this documented anywhere? Is this guaranteed to stay consistent in the future?

I’d also like to point out that the View documentation behaviour is really odd. The notion of a “first file” by name sorting might not even be consistent across file systems. And it prevents us from organizing our Documentation~/ folder in any way. GitHub for instance will always display README.md when entering a directory.

Likewise, View licenses is misleading. On the Asset Store for example, we must include a LICENSES (plural) file that notes all third party licenses for all dependencies in the asset. In PacMan, it seems like although the View licenses button is plural, it will only fetch and display the singular LICENSE.md, usually only containing the project’s own license.

I would be great to have a clear list of attempted paths. For example:

  • View documentation

  • Documentation~/README.md

  • Documentation~/index.html

  • View changelog

  • CHANGELOG.md

  • View licenses

  • LICENSES.md

  • LICENSE.md

2

I notice the Malimbe package uses THIRD_PARTY_NOTICES.md for 3rd party licenses.
Is that a standard/official format?

3

Hi @LazloBonin ,

See the Package Layout section in the Unity User Manual for the official documentation and current conventions.

It should stay consistent. We may introduce new files or configuration locations, but these, as far as I can tell, will be supported for a long time.

Yes, we are aware. We plan to support more complex documentation generation outside of Unity. There is something for internal Unity package developers but we are not ready to share the tooling with you at the moment. Right now, you are stuck with the one MD file limitation. And yes, you are right, the UI will look up for the first one in the folder. Expect improvements for this flow in the future.

I believe the UI does not expose this file for the moment. But, this is a standard way to expose your third party license requirement. See the Meeting Legal Requirements section in the Unity User Manual.

Regards,

Pascal

4

Hi Pascal! Thanks for the followup.

If you’re curious, here’s how I’m working in the mean time for my publicly maintained package GoCS.

My Documentation~/ folder:

  • Root only contains a single README.md so that GitHub displays it

  • All other files are put in sub folders to make sure Unity doesn’t open them by default

  • Manual/ for the user manual

  • API/ for the API reference

To generate the API, I have a very convoluted setup, because Unity doesn’t generate XML docs from ASMDEF files. If it did, it would be a simple matter of throwing the .xml file at any documentation generator available online (there are dozens), but currently I have to:

  • Create a separate Visual Studio project and solution for the package
  • Add all package files
  • Add Unity DLL references which I can’t redistribute
  • Work around my preprocessor directives
  • Set it to generate the XML documentation
  • Add a Nuget package to generate Markdown from the XML doc file
  • Hide the whole project under a DocumentationGeneration~/ folder so Unity doesn’t import it (this is tricky to get right with the package paths…)

The doc I package for executing that is: gocs/DocumentationGeneration~ at master · lazlo-bonin/gocs · GitHub

And the result looks like: https://github.com/lazlo-bonin/gocs/blob/master/Documentation~/API/API.md

It’s far from perfect but it does the job. In the future, proper documentation tooling would be great (or at the very least a way for us to enable .XML file generation from ASMDEFs!).

5

Hi @LazloBonin ,

This is really great. Impressive work. But I can’t wait for the day where you can throw it away for a good built-in solution :stuck_out_tongue:

Thank you for sharing!

Pascal

6

I’m looking into adding documentation links for our custom packages, and by looking at unity’s packages I’m wondering how the “View documentation” links on these packages can open a URL, while in ours it looks for a local file.

7

Hello @MagicDesignEmerick
We indeed have some tooling internally to have our documentation shown online.
However, that tooling is not out yet for external packages and only the local file path is shown.
But you can expect improvement on that in the future.