Allow for plugins to provide docs in NetBox UI

[ryanmerolle]

NetBox version

v3.2.7

Feature type

Change to existing functionality

Proposed functionality

Currently get_docs_url does not allow for plugins to include their docs. It would be a nice feature if it did.

@register.filter()
def get_docs_url(model):
    """
    Return the documentation URL for the specified model.
    """
    return f'{settings.STATIC_URL}docs/models/{model._meta.app_label}/{model._meta.model_name}/'

Use case

Allow for higher quality plugins with documents in the NetBox UI just like any other model.

Database changes

N/A

External dependencies

N/A

[jeremystretch]

I'm not sure just exposing a resolution method would be sufficient: How would the plugin's content actually make it into the compiled documentation? It seems we would need a mechanism to pull in Markdown files from each plugin (and extend the table of contents) prior to building the documentation.

[ryanmerolle]

Does it need to be compiled into the full documentation? I am only talking about the doc link in each model’s pages.

Maybe we could pass a yaml or json file with the plugin if it’s easier.

[jeremystretch]

I'm sure we could make something work, but it would be a lot cleaner to stay consistent with the rest of the docs. And ideally we'd have some way to handle rendering the source Markdown on behalf of the plugin, rather than requiring a plugin to ship HTML documentation.

[jeremystretch]

I guess we could declare a get_docs_url() method on the base model class, to replace the get_docs_url template tag (above) which currently assumes a documentation page is available locally at /docs/models/<app_label>/<model_name>/. A plugin model can override this to point to e.g. the plugin's own ReadTheDocs page. This breaks support for offline-only deployments, but that may be a reasonable compromise in lieu of a more robust solution.