Allow for plugins to provide docs in NetBox UI #6747

New Issue

adam · 2025-12-29T19:44:55+01:00

adam commented

2025-12-29 19:44:55 +01:00

Originally created by @ryanmerolle on GitHub (Jul 30, 2022).

Originally assigned to: @jeremystretch on GitHub.

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

Originally created by @ryanmerolle on GitHub (Jul 30, 2022). Originally assigned to: @jeremystretch on GitHub. ### NetBox version v3.2.7 ### Feature type Change to existing functionality ### Proposed functionality Currently [get_docs_url](https://github.com/netbox-community/netbox/blob/develop/netbox/utilities/templatetags/helpers.py#L146-L151) does not allow for plugins to include their docs. It would be a nice feature if it did. ```python @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

adam added the status: accepted type: feature topic: plugins labels 2025-12-29 19:44:55 +01:00

adam closed this issue

2025-12-29 19:44:56 +01:00

adam commented

2025-12-29 19:44:56 +01:00

@jeremystretch commented on GitHub (Oct 17, 2022):

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.

@jeremystretch commented on GitHub (Oct 17, 2022): 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.

adam commented

2025-12-29 19:44:56 +01:00

@ryanmerolle commented on GitHub (Oct 18, 2022):

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.

@ryanmerolle commented on GitHub (Oct 18, 2022): 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.

adam commented

2025-12-29 19:44:56 +01:00

@jeremystretch commented on GitHub (Oct 18, 2022):

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 commented on GitHub (Oct 18, 2022): 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.

adam commented

2025-12-29 19:44:56 +01:00

@jeremystretch commented on GitHub (Oct 26, 2022):

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.

@jeremystretch commented on GitHub (Oct 26, 2022): 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.

Sign in to join this conversation.

Branches Tags

main

update-changelog-comments-docs

feature-removal-issue-type

20911-dropdown

20239-plugin-menu-classes-mutable-state

21097-graphql-id-lookups

feature

fix_module_substitution

20923-dcim-templates

20044-elevation-stuck-lightmode

feature-ip-prefix-link

v4.5-beta1-release

20068-import-moduletype-attrs

20766-fix-german-translation-code-literals

20378-del-script

7604-filter-modifiers-v3

circuit-swap

12318-case-insensitive-uniqueness

20637-improve-device-q-filter

20660-script-load

19724-graphql

20614-update-ruff

14884-script

02496-max-page

19720-macaddress-interface-generic-relation

19408-circuit-terminations-export-templates

20203-openapi-check

fix-19669-api-image-download

7604-filter-modifiers

19275-fixes-interface-bulk-edit

fix-17794-get_field_value_return_list

11507-show-aggregate-and-rir-on-api

9583-add_column_specific_search_field_to_tables

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/netbox#6747