Add the ability to download an offline version of the documentation

[yuvashankar]

Is your feature request related to a problem? Please describe.
When configuring networks without an secondary internet connection, it is desirable to have an offline copy of the documentation. I cannot find any method of downloading the OPNSense documentation for offline viewing.

Describe the solution you like

I would like to have an offline PDF or some sort of file of the documentation to view without an internet connection.

Describe alternatives you considered

1. I tried a cursory internet search to see if this was available in another format. I found this article that described how to manually perform this operation.
   https://forum.opnsense.org/index.php?topic=38918.0

This is a quick solution that I've devised. I mainly did it so that I could generate the PDF for myself. I have no idea if this is the optimal solution, I have no plans to support this. I used a Nix Flake to generate a singlefile HTML, and then fed it to pandoc to generate the PDF for me.

{
  description = "Nix flake for building opnsense/docs (Sphinx-based documentation)";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs =
    {
      self,
      nixpkgs,
      flake-utils,
    }:
    flake-utils.lib.eachDefaultSystem (
      system:
      let
        pkgs = import nixpkgs { inherit system; };
        python3 = pkgs.python3;
        blockdiagcontrib-cisco = pkgs.python3Packages.buildPythonPackage rec {
          pname = "blockdiagcontrib-cisco";
          version = "0.1.8";
          pyproject = true;
          build-system = with python3.pkgs; [
            setuptools
            blockdiag
          ];
          src = python3.pkgs.fetchPypi {
            inherit pname version;
            sha256 = "sha256-IvOXUvXhmByTzgNNdJ+Y1l2w80gVfV/ZW3Q8wgMePBo=";
          };
          propagateBuildInputs = with python3.pkgs; [ blockdiag ];
        };
        pythonEnv = python3.withPackages (
          ps: with ps; [
            # sphinx
            sphinx-rtd-theme # Optional: ReadTheDocs theme
            blockdiag
            nwdiag
            seqdiag
            actdiag
            sphinx-sitemap
            sphinx-tabs
            sphinxcontrib-blockdiag
            sphinxcontrib-nwdiag
            sphinxcontrib-seqdiag
            blockdiagcontrib-cisco
            sphinxcontrib-actdiag
            pillow
            ply
            pydantic
          ]
        );
      in
      {

        packages.default = pkgs.stdenv.mkDerivation {
          pname = "opnsense-docs";
          version = "0.1.0";
          src = self;
          buildInputs = with pkgs; [
            pythonEnv
            gnumake
            haskellPackages.jpeg-turbo
            git
            texliveFull
            sphinx
            typst
            pandoc
            python313Packages.weasyprint
            wkhtmltopdf
            wget
          ];
          buildPhase = ''
            # There are some images that don't render with the singlehtml I think...
            make html
            make singlehtml 
            # Manually copy the images from the manual into the single html directory.
            cp -r build/html/manual/ build/singlehtml/
            cd build/singlehtml/

            pandoc index.html -f html --pdf-engine wkhtmltopdf --pdf-engine-opt="--disable-smart-shrinking" -o output.pdf
          '';
          installPhase = ''
            mkdir -p $out
            cp output.pdf $out/
          '';

        };

        # Dev shell for docs work
        devShells.default = pkgs.mkShell {
          buildInputs = with pkgs; [
            pythonEnv
            gnumake
            haskellPackages.jpeg-turbo
            texliveFull
            typst
            pandoc
            python313Packages.weasyprint
            sphinx-autobuild
            wkhtmltopdf
            wget
          ];
        };
      }
    );
}

Additional context
I was unsure about what was supposed to be substituted when trying to update the API endpoints. I simply ran the commands and pointed it to the opensense/core and plugin repositories. For example:

./collect_api_endpoints.py --repo core https://github.com/opnsense/core/

To build this, install nix, ensure you enable the flakes feature, then run nix build within the repository. The resulting file is result/output.pdf.

[Monviech]

I feel like this is natively supported by read the docs. When cloning this repositories these should be available when configured:

https://docs.readthedocs.com/platform/latest/downloadable-documentation.html

I dunno though never tried it.

[yuvashankar]

I feel like this is natively supported by read the docs. When cloning this repositories these should be available when configured:

https://docs.readthedocs.com/platform/latest/downloadable-documentation.html

I dunno though never tried it.

Thanks for the link @Monviech , in my haste I forgot to mention that I had done a cursory internet search prior to building it with the Nix flake.

• I found this forum post with a similar suggestion. I had tried to create a .readthedocs.yaml config file, however I was not sure if it the config took, or if the specified menu was not being displayed. I wasn't confident in my sphinx docs framework to go code spelunking.

• I also found similar questions being asked in other Github Issues here that aged out with no way for me to build it locally.

To reiterate, I sincerely appreciate the documentation you've provided us. I made my solution available for the community, hopefully it's a good starting point for whomever has the same needs.

Cheers!