Include docs in main release

[jcralbino]

I believe it will be better for situation where netbox is deployed in a closed air gap management environment that the documentation is included in the deployment.

When installing netbox we are getting only the source code for the application, while the documentation is available online in https://netbox.readthedocs.io/en/stable/

What I propose is to allow netbox deployment to provide also a link to the documentation that would be provided alongside the netbox source code

This would facilitate its understanding in environments where internet access is not provided

Regards
Jose

[candlerb]

When installing netbox we are getting only the source code for the application

That's not true - the documentation is in the docs subdirectory (of both a git checkout and a release tarball), albeit in its raw markdown form.

Personally I don't support either including HTML-rendered documentation, or the tools to render markdown, within the main Netbox source and/or releases.

Having a separate download for the rendered HTML (or PDF) documentation for offline reading is IMO a more reasonable request.

[jcralbino]

Indeed my objective of this thread was to see if we can have the rendered HTML documentation available for offline reading and also to have the link changed to use an internal url behind main netbox url.

I understand from your comment the following:

1. The source code used for the online documentation on https://netbox.readthedocs.io/en/stable/, is available in the source code under docs ( although not being used currently)
2. Although the source code of the documentation is there it is not used.
3. Although the markdown is used in the comments field in netbox, this is probably a lite version ?
4. The only change required in netbox to provide the documentation offline is to include all required tools to render markdown completely and configure nginx properly to include the new url ?

In my opinion considering the source code is there, providing the required tools to render the raw markdown would make sense, but i do not understand completely that implication in terms of resources of the machine.

But it would be interesting to take that functionality also and increase the core functionality of the netbox platform as it would give it more documentation functionalities. One that i am interested is the capacity to render network diagrams from source text files. ( something on the likes of https://github.com/blockdiag/nwdiag)

[candlerb]

The documentation is compiled using mkdocs with the material theme. You wouldn't want to run the preview server, so you'd need a rendering step to convert it to HTML (either way involve installing mkdocs and all its dependencies). If you're going to do that, you might as well just download the HTML from somewhere.

Re network diagrams, there's been discussion about this before. Now that netbox supports plugins then it would be up to third parties to implement this: integrated drawing has been rejected (e.g. #1827), and the simple graphviz topology rendering which Netbox originally had was removed in v2.7.

Another drawing backend which you might want to look into is drawthe.net.

[devon-mar]

Perhaps a tar/zip of the docs could be attached to the GitHub release instead.

[rodvand]

Another benefit of including the html docs in the release is that the documentation is related to the specific version being used. So if someone is stuck on 2.11.2 they have documentation covering this specific release, even if the current release is 2.13.

[jcralbino]

Good.
Do you want me to create a feature requested for this.

[jeremystretch]

@jcralbino please do!

[jcralbino]

Feature request here:
#6328