Search Unity

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

Discussion in 'Package Manager' started by Ludiq, Oct 22, 2019.

  1. Ludiq

    Ludiq

    Joined:
    Mar 6, 2015
    Posts:
    618
    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
      1. Documentation~/README.md
      2. Documentation~/index.html
    • View changelog
      1. CHANGELOG.md
    • View licenses
      1. LICENSES.md
      2. LICENSE.md
     
  2. Ludiq

    Ludiq

    Joined:
    Mar 6, 2015
    Posts:
    618
  3. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    610
    Hi @Ludiq,

    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
     
    Last edited: Oct 23, 2019
  4. Ludiq

    Ludiq

    Joined:
    Mar 6, 2015
    Posts:
    618
    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:
    https://github.com/lazlo-bonin/gocs/tree/master/Documentation~
    • 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: https://github.com/lazlo-bonin/gocs/tree/master/DocumentationGeneration~

    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. okcompute_unity

    okcompute_unity

    Unity Technologies

    Joined:
    Jan 16, 2017
    Posts:
    610
    Hi @Ludiq ,

    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 :p

    Thank you for sharing!

    Pascal
     
  6. MagicDesignEmerick

    MagicDesignEmerick

    Joined:
    Oct 4, 2017
    Posts:
    16
    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. cassandraL

    cassandraL

    Unity Technologies

    Joined:
    Dec 7, 2017
    Posts:
    108
    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.