starred/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2026-01-11 21:10:29 +01:00
Code Issues 273 Packages Projects Releases 10 Wiki Activity

Implement contextual UI documentation #3359

New Issue
Closed
opened 2025-12-29 18:28:17 +01:00 by adam · 1 comment
adam commented 2025-12-29 18:28:17 +01:00
Owner
Copy Link

Originally created by @jeremystretch on GitHub (Feb 20, 2020).

Originally assigned to: @jeremystretch on GitHub.

Environment

  • Python version: 3.6.9
  • NetBox version: 2.7.7

Proposed Functionality

Embed documentation for specific objects or concepts directly within the UI. For example, when viewing the "Add device" form, there will be a small "help" button to the side. When clicked, it displays a modal (sort of an in-page pop-up dialog) with the contents of the documentation section relating to the Device model. The content itself would be served via an API endpoint, e.g. /api/docs/?content=models.dcim.device.

To avoid redundancy, we can restructure our current documentation to be more modular. For example, the documentation for devices, device types, and related models all exists in the file docs/core-functionality/devices.md. We can split out these sections so that each file model gets its own file:

  • docs/models/dcim/devicetype.md
  • docs/models/dcim/device.md
  • docs/models/dcim/interface.md
  • etc.

Of course, this would be rather tedious to navigate on ReadTheDocs: Someone who's reading up on device modeling in NetBox would probably prefer to see all related models on one page. We can accomplish this using markdown_include plugin for mkdocs to pull in content from multiple files into a single easily-browsed page:

# Device Modeling in NetBox

Preamble goes here...

{!docs/models/dcim/devicetype.md!}
{!docs/models/dcim/device.md!}
...

This approach allows us to serve the core content both on RTD and directly within the UI.

Use Case

This proposal has several benefits:

  1. Provide immediate access to contextual documentation directly within the UI
  2. Enable cross-utilization of content through the UI and ReadTheDocs
  3. Enforce a more modular, predictable structure for documentation
  4. Gaps in the existing documentation will be identified as we deploy links within the UI

Database Changes

None

External Dependencies

We'll need markdown_include to render the documentation, however we should be able to avoid adding it to NetBox's root requirements.txt file. RTD supports a YAML configuration file which should allow us to specify a separate requirements file used to build the documentation site.

Originally created by @jeremystretch on GitHub (Feb 20, 2020). Originally assigned to: @jeremystretch on GitHub. ### Environment * Python version: 3.6.9 * NetBox version: 2.7.7 ### Proposed Functionality Embed documentation for specific objects or concepts directly within the UI. For example, when viewing the "Add device" form, there will be a small "help" button to the side. When clicked, it displays a modal (sort of an in-page pop-up dialog) with the contents of the documentation section relating to the Device model. The content itself would be served via an API endpoint, e.g. `/api/docs/?content=models.dcim.device`. To avoid redundancy, we can restructure our current documentation to be more modular. For example, the documentation for devices, device types, and related models all exists in the file `docs/core-functionality/devices.md`. We can split out these sections so that each file model gets its own file: * `docs/models/dcim/devicetype.md` * `docs/models/dcim/device.md` * `docs/models/dcim/interface.md` * etc. Of course, this would be rather tedious to navigate on [ReadTheDocs](https://netbox.readthedocs.io): Someone who's reading up on device modeling in NetBox would probably prefer to see all related models on one page. We can accomplish this using [`markdown_include`](https://github.com/sethen/markdown-include) plugin for `mkdocs` to pull in content from multiple files into a single easily-browsed page: ``` # Device Modeling in NetBox Preamble goes here... {!docs/models/dcim/devicetype.md!} {!docs/models/dcim/device.md!} ... ``` This approach allows us to serve the core content both on RTD and directly within the UI. ### Use Case This proposal has several benefits: 1. Provide immediate access to contextual documentation directly within the UI 2. Enable cross-utilization of content through the UI and ReadTheDocs 3. Enforce a more modular, predictable structure for documentation 4. Gaps in the existing documentation will be identified as we deploy links within the UI ### Database Changes None ### External Dependencies We'll need [`markdown_include`](https://github.com/sethen/markdown-include) to render the documentation, however we should be able to avoid adding it to NetBox's root `requirements.txt` file. RTD supports a [YAML configuration file](https://docs.readthedocs.io/en/stable/config-file/v2.html) which should allow us to specify a separate requirements file used to build the documentation site.
adam added the status: acceptedtype: feature labels 2025-12-29 18:28:17 +01:00
adam closed this issue 2025-12-29 18:28:17 +01:00
adam commented 2025-12-29 18:28:17 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Mar 6, 2020):

This ended up involving quite a bit of work, including ditching py-gfm in favor of a more recent Markdown release. Everything is staged in the 4217-contextual-docs branch. Probably going to wait for v2.7.10 to merge it.

@jeremystretch commented on GitHub (Mar 6, 2020): This ended up involving quite a bit of work, including ditching `py-gfm` in favor of a more recent Markdown release. Everything is staged in the `4217-contextual-docs` branch. Probably going to wait for v2.7.10 to merge it.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
beta
breaking change
complexity: high
complexity: low
complexity: medium
needs milestone
netbox
pending closure
plugin candidate
pull-request
Mirrored from GitHub Pull Request
 severity: high
severity: low
severity: medium
status: accepted
status: backlog
status: blocked
status: duplicate
status: needs owner
status: needs triage
status: revisions needed
status: under review
topic: GraphQL
topic: Internationalization
topic: OpenAPI
topic: UI/UX
topic: cabling
topic: event rules
topic: htmx navigation
topic: industrialization
topic: migrations
topic: plugins
topic: scripts
topic: templating
topic: testing
type: bug
type: deprecation
type: documentation
type: feature
type: housekeeping
type: translation
No Label status: accepted type: feature
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/netbox#3359
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?