Offline documenation available for download

[eric72777]

• [x] I have read the contributing guide lines at https://github.com/opnsense/docs/blob/master/CONTRIBUTING.md
• [x] I have searched the existing issues and I am convinced that mine is new.

Request

In the event that my internet and router are down, I would like to have a local, offline copy of the opnsense documentation. This offline copy should be easily accessible for users on your documentation (e.g., I shouldn't need to compile the documentation).

Solution

Ideally, I'd like a single epub or pdf of all opnsense documentation pages available as a download. This file could be linked on the main page, like on pfsense docs (https://docs.netgate.com/pfsense/en/latest/) or could be linked on the sidebar, like on Read the Docs (https://docs.readthedocs.io/en/stable/). I would like for this file to always have the latest/current documentation.

In case it's helpful, here are some reference Read the Docs links: https://docs.readthedocs.io/en/stable/guides/enable-offline-formats.html https://docs.readthedocs.io/en/stable/downloadable-documentation.html https://docs.readthedocs.io/en/latest/tutorial/index.html#enabling-pdf-and-epub-builds

[arcticpinecone]

Hello,

I would like to add to this, the same request/requirement. It's really not logical why this is not already something available. We are specifically working with network connectivity devices. An offline manual feels like it should be a no brainer. Especially one we don't have to compile first... 🧠

I came looking for this specifically today when going for the 23.1 -> 23.7 upgrade. This should be taken seriously.

[fichtner]

It's probably counter-productive to add a static file that is outdated every week as a download, but that's just my personal belief.

It would make more sense to bundle the help in the opnsense package (or as a dependency such as opnsense-lang does it) in order to ship a matching documentation with the OPNsense version at hand. But this will take time and is not a priority.

[arcticpinecone]

It's frustrating thinking it is not being heard fully what is being said or requested.

They are automatically built by Read the Docs during our default build process, as long as you have the configuration enabled to turn this on. How to enable offline formats

You went with personal belief/understanding instead of looking at the several links pointed to this exact issue by the original poster. Or even thought about the user base and their possible use cases.

[fichtner]

I think you simply don't like the answer: there are no plans to publish a PDF is all I am saying.

Cheers, Franco

[arcticpinecone]

So you won't enable the functionality for PDFs or HTML to automatically be created and downloaded, and allow your userbase access to the public help documentation.. because... you don't want to. Got it.

[fichtner]

FWIW, communication is key.

Cheers, Franco

[arcticpinecone]

Yes indeed it is. You came out the gate swinging with your personal belief that you have a against a static file which is 'outdated every week'.

• It was shown to you by two people that it's something which is automatically generated based on the existing published version of the documentation.
• Also something you don't have to even create on your own.
• You add that it 'takes time' and not something you will do. Despite being a configuration change in the existing document creation system you use.

So yes, communication is clearly coming from us that this is here, it's easy, and desired. You dismiss it based on no good reason, and further are rude that we just 'don't like the answer'.

Sure, at least I don't appreciate power tripping people saying no to something which is so ridiculously easy to enable and do, but you prefer not to because... we're the problem here. I guess? 🤣🤣🤣🤣🤣

[fichtner]

You start to cut into other people's community support time here. I don't consider this a good trait.

Technical and administrative work aside the PDF file will practically be outdated as soon as it is being downloaded and cause more traffic on the server than a traditional website. As such the website is more useful also because it automatically updates. We want the same for the OPNsense releases so you can have the best offline experience if that matters.

For everything else I'm sure both of us have better things to do.

Cheers, Franco

[AdSchellevis]

@arcticpinecone how often have you actually tried to build our docs and generate a pdf???? It's not that we're not publishing anything here.... (if it would be generated by default using the steps we take, it would have been here...). Personally I don't mind that much publishing other formats, but the time it takes to keep up every time does matter (including the breakage of third party tools). Sometimes it would be nice if in stead of complaining, someone would actually make an effort.

[OPNsense-bot]

This issue has been automatically timed-out (after 180 days of inactivity).

For more information about the policies for this repository, please read https://github.com/opnsense/docs/blob/master/CONTRIBUTING.md for further details.

If someone wants to step up and work on this issue, just let us know, so we can reopen the issue and assign an owner to it.