Standardise documentation links to ensure they work across local and production environments

[marcus-crane]

Change Type

[ ] Addition
[ ] Correction
[ ] Deprecation
[x] Cleanup (formatting, typos, etc.)

Area

[x] Installation instructions
[x] Configuration parameters
[x] Functionality/features
[x] REST API
[x] Administration/development
[x] Other

Proposed Changes

tl;dr Change all links to follow the [Document title](../category/name.md#ref) format for ease of development

I've noticed a couple of broken links in the production version of the Netbox documentation that work fine locally.

The links in question use the /category/blah style of URL which works fine locally but doesn't work in production as this type of link translates into netbox.readthedocs.io/category/blah which invalid because the documentation lives under netbox.readthedocs.io/en/stable/category.blah

Similarly, most every working link is formatted as ../../category/blah which works fine locally and in production but has no correlation to the folder structure on disc, adding a bit of overhead when juggling between the disk layout and the deploy layout

I notice that mkdocs will transform a filesystem link (ie ../configuration/index.md#blah) into a proper URL (ie ../../configuration/) and seems like the best of both worlds. You only have to think about the folder structure on disc and it has the added benefit of being a valid link locally so you can traverse through the documentation while using markdown preview built into text editors or a dedicated markdown previewer such as MacDown

I've gone through the documentation locally and made these changes but as this would be my first pull request on behalf of my employer (Daimler / Mercedes-Benz Trucks), I've still yet to gain access to our Github org which is a blocker for my contributing a PR. For now, I'll just post a proposal anyway to see if it's accepted 🙂

^{Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS (Imprint)}

[DanSheps]

Just a note, you can do the PR under your personal account.

I am not sure how this would affect our readthedocs build yet.

[marcus-crane]

@DanSheps Heya, normally I'd just use my personal account but it's part of the contributing guidelines we have internally that we first fork to the Daimler Github org and then file a pull request from there.

I think there are a few instances already of documentation links following the ../category/document.md style so I'd expect them to work as expected in production without any changes to the current readthedocs configuration.

I can file a PR for review once/if this is marked as accepted given the contribution guidelines say that any PRs before then will be rejected 🙂

Given that, you can feel free to assign this issue to me as well.

^{Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS (Imprint)}

[marcus-crane]

Heya,

Just following up on this issue as I'm not able to contribute my documentation changes without this issue being marked as accepted.

For what it's worth, there are a few broken links in the current live documentation site such as Development -> Getting Started which I personally fumbled with while trying to set up Netbox and write a plugin. I'm hoping I can fix these for other users going forward.

Regarding the understandable concern about how this would work with the Read The Docs build, you're already using some of the relative links I described in production right now. Here is an example which you can see with the "Installation docs" link.

Let me know if you need anything else from my end, or if there are any other considerations to take into account.

Thanks!

^{Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS (Imprint)}

[marcus-crane]

Hi there,

I just wanted to know if this was still under review?

The links mentioned are still broken in your production documentation but if there's no interest, I'm happy to close this issue.

I've had a branch with the changes sitting on my hard drive since December so I'm happy to own this issue but I can't submit a PR until this issue is reviewed as was requested in the Netbox contributor guidelines

Kind Regards 😊

^{Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS (Imprint)}

[DanSheps]

Sorry, you can go ahead and submit the PR.