search

nornir-automation / nornir

Pluggable multi-threaded framework with inventory management to help operate collections of devices
https://nornir.readthedocs.io/
Apache License 2.0
1.37k stars 233 forks source link

Docs - fixing several broken hyperlinks #904

Closed mjbear closed 4 months ago

mjbear commented 5 months ago

Hello. It's nice to virtually meet you. :grinning:

I saw the notes on issue #593 and figured I can pitch in to fix some links up!

I believe I've accurately identified the corresponding readthedocs URL, but another set of eyes (please) couldn't hurt. Thank you!

I'd be glad to submit PRs for these docs fixes (once there's some feedback). Would the maintainers prefer a PR per documentation file?

nornir]$ grep -ron 'ref/api' docs/*
docs/howto/handling_connections.ipynb:67:ref/api
docs/howto/handling_connections.ipynb:67:ref/api
docs/howto/handling_connections.ipynb:67:ref/api
docs/howto/handling_connections.ipynb:67:ref/api
docs/howto/handling_connections.ipynb:122:ref/api
docs/tutorial/initializing_nornir.ipynb:146:ref/api
docs/tutorial/failed_tasks.ipynb:381:ref/api
docs/tutorial/failed_tasks.ipynb:408:ref/api
docs/tutorial/failed_tasks.ipynb:408:ref/api
docs/tutorial/processors.ipynb:9:ref/api

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/tutorial/processors.ipynb#L9 discussed on issue #593

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/tutorial/initializing_nornir.ipynb#L146 intent is probably linking to https://nornir.readthedocs.io/en/latest/api/nornir/init_nornir.html#nornir.init_nornir.InitNornir

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/tutorial/failed_tasks.ipynb#L381 intent seems to be https://nornir.readthedocs.io/en/latest/api/nornir/core/state.html#nornir.core.state.GlobalState

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/tutorial/failed_tasks.ipynb#L408 https://nornir.readthedocs.io/en/latest/api/nornir/core/state.html#nornir.core.state.GlobalState.recover_host and https://nornir.readthedocs.io/en/latest/api/nornir/core/state.html#nornir.core.state.GlobalState.reset_failed_hosts

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/howto/handling_connections.ipynb#L67 https://nornir.readthedocs.io/en/latest/api/nornir/core/inventory.html#nornir.core.inventory.Host.open_connection and https://nornir.readthedocs.io/en/latest/api/nornir/core/inventory.html#nornir.core.inventory.Host.close_connection and https://nornir.readthedocs.io/en/latest/api/nornir/core/inventory.html#nornir.core.inventory.Host.close_connections and https://nornir.readthedocs.io/en/latest/api/nornir/core/__init__.html#nornir.core.__init__.Nornir.close_connections

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/howto/handling_connections.ipynb#L122 https://nornir.readthedocs.io/en/latest/api/nornir/core/inventory.html#nornir.core.inventory.Host.open_connection

mjbear commented 4 months ago

Been a few days so I thought I'd ping this thread. Thank you! @dbarrosop @ubaumann

dbarrosop commented 4 months ago

Hi, sorry about that. Thanks for identifying the broken links, the tricky bit here is that the paths should be generated by sphinx rather than be hardcoded (otherwise links might point to the wrong thing in some cases). I dropped a comment in the PR you opened with an example.

mjbear commented 4 months ago

All good. This makes sense. Thank you for guiding me!

Hopefully these relative paths are correct.

As long as the processors PR goes well then I'll work up changes for the list below.

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/tutorial/initializing_nornir.ipynb#L146

../api/init_nornir.rst#nornir

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/tutorial/failed_tasks.ipynb#L381

../api/nornir.rst#nornir.core.state.GlobalState

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/tutorial/failed_tasks.ipynb#L408

../api/nornir.rst#nornir.core.state.GlobalState.recover_host
../api/nornir.rst#nornir.core.state.GlobalState.reset_failed_hosts

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/howto/handling_connections.ipynb#L67

../api/inventory.rst#nornir.core.inventory.Host.open_connection
../api/inventory.rst#nornir.core.inventory.Host.close_connection
../api/inventory.rst#nornir.core.inventory.Host.close_connections
../api/nornir.rst#nornir.core.Nornir.close_connections

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/howto/handling_connections.ipynb#L122

../api/inventory.rst#nornir.core.inventory.Host.open_connection

dbarrosop commented 4 months ago

I think this one can be close, can't it? Feel free to reopen otherwise.

mjbear commented 3 weeks ago

:dart: Once I figure out how to get sphinx working so I can perform a local test then I'll know for sure. :trophy: And from there I can confidently submit PR(s) to fix these links.

All good. This makes sense. Thank you for guiding me!

Hopefully these relative paths are correct.

As long as the processors PR goes well then I'll work up changes for the list below.

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/tutorial/initializing_nornir.ipynb#L146

../api/init_nornir.rst#nornir

InitNornir docs link doesn't 404, so it is fixed at the current date+time. Good. :smile:

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/tutorial/failed_tasks.ipynb#L381

../api/nornir.rst#nornir.core.state.GlobalState

Correction: ../../api/nornir/core/state.rst#nornir.core.state.GlobalState

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/tutorial/failed_tasks.ipynb#L408

../api/nornir.rst#nornir.core.state.GlobalState.recover_host
../api/nornir.rst#nornir.core.state.GlobalState.reset_failed_hosts

Correction:

../../api/nornir/core/state.rst#nornir.core.state.GlobalState.recover_host
../../api/nornir/core/state.rst#nornir.core.state.GlobalState.reset_failed_hosts

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/howto/handling_connections.ipynb#L67

../api/inventory.rst#nornir.core.inventory.Host.open_connection
../api/inventory.rst#nornir.core.inventory.Host.close_connection
../api/inventory.rst#nornir.core.inventory.Host.close_connections
../api/nornir.rst#nornir.core.Nornir.close_connections

Correction:

../api/nornir/core/inventory.rst#nornir.core.inventory.Host.open_connection
../api/nornir/core/inventory.rst#nornir.core.inventory.Host.close_connection
../api/nornir/core/inventory.rst#nornir.core.inventory.Host.close_connections

../api/nornir/core/__init__.rst#nornir.core.__init__.Nornir.close_connections

https://github.com/nornir-automation/nornir/blob/95ef20f6a00b57d0e7dc6c5382c3618c7b43a44b/docs/howto/handling_connections.ipynb#L122

../api/inventory.rst#nornir.core.inventory.Host.open_connection

Correction: ../api/nornir/core/inventory.rst#nornir.core.inventory.Host.open_connection