WIP Refactor docs to be consistent with other kartoza projects

.gitignore

@@ -118,6 +118,8 @@ venv.bak/
 
 # mkdocs documentation
 /site
+/docs/site
+/docs/pdfs
 
 # mypy
 .mypy_cache/

admin.py

@@ -407,31 +407,19 @@ def _get_metadata() -> typing.Dict:
     with config_path.open("r") as fh:
         conf = json.load(fh)
     general_plugin_config = conf["general"]
+    changelog = conf["general"]["changelog"]
+
     metadata = general_plugin_config
 
     metadata.update(
         {
             "tags": ", ".join(general_plugin_config.get("tags", [])),
-            "changelog": _changelog(),
+            "changelog": changelog,
         }
     )
     return metadata
 
 
-def _changelog() -> str:
-    """Reads the changelog content from a config file.
-
-    :returns: Plugin changelog
-    :type: str
-    """
-    path = LOCAL_ROOT_DIR / "docs/plugin/changelog.txt"
-
-    with path.open() as fh:
-        changelog_file = fh.read()
-
-    return changelog_file
-
-
 def _add_to_zip(directory: Path, zip_handler: zipfile.ZipFile, arc_path_base: Path):
     """Adds to files inside the passed directory to the zip file.
 

docs/.envrc

@@ -0,0 +1,2 @@
+use nix
+layout python3

docs/.gitignore

@@ -0,0 +1,4 @@
+site
+templates/styles.scss
+pdfs/*.pdf
+mkdocs.yml

docs/README.md

@@ -0,0 +1,217 @@
+# Building documentation
+
+## Preparing your Environment
+
+The general workflow we recommend is:
+
+1. Install the nix package manager
+2. Checkout this project
+3. Open this docs folder in a shell / terminal application
+4. Open a nix-shell to install the build environment
+
+### Install Nix package manager
+
+If you are on ubuntu, windows (under WSL2) or macOS you can install the nix
+package manager which will fetch all the dependencies needed to build this
+project.
+
+To do this, please go to the [Nix Download Page](https://nixos.org/download) and follow the instructions
+under `Nix: the package manager` as appropriate to your operating system.
+
+A special note for NixOS users:
+
+If you are a NixOS user, you already have the nix package manager. You can
+additionally install [direnv](https://github.com/nix-community/nix-direnv)
+which will create a seamless entry into the development environment.
+
+### Checkout this project
+
+You need to have a local copy of this project in order to build the documentation. To do that you can do:
+
+```
+git clone https://github.com/kartoza/cplus-plugin.git
+```
+
+or
+
+```
+git clone [email protected]:kartoza/cplus-plugin.git
+```
+
+### Open the project in your terminal
+
+Open your favourite terminal and enter into this documentation folder:
+
+```
+cd cplus-plugin/docs/
+```
+
+### Install the build environment
+
+Now we can set up the build environment. Note that it will fetch a bunch of
+packages from the internet, so having a good internet connection will help a
+lot here.
+
+```
+nix shell
+```
+
+Note: As mentioned above, if you have direnv set up on NixOS, you can skip this
+step, it is automatic.
+
+When the setup process completes, you will see something like this in your shell:
+
+
+```
+direnv: loading ~/dev/python/cplus-plugin/docs/.envrc
+direnv: using nix
+Using venvShellHook
+Executing venvHook
+Skipping venv creation, './.venv' already exists
+Finished executing venvShellHook
+direnv: export +AR +AS +CC +CONFIG_SHELL +CXX +DETERMINISTIC_BUILD +GETTEXTDATADIRS +GETTEXTDATADIRS_FOR_TARGET +GSETTINGS_SCHEMAS_PATH +HOST_PATH +IN_NIX_SHELL +LD +NIX_BINTOOLS +NIX_BINTOOLS_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_BUILD_CORES +NIX_BUILD_TOP +NIX_CC +NIX_CC_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_CFLAGS_COMPILE +NIX_ENFORCE_NO_NATIVE +NIX_HARDENING_ENABLE +NIX_LDFLAGS +NIX_SSL_CERT_FILE +NIX_STORE +NM +OBJCOPY +OBJDUMP +PYTHONHASHSEED +PYTHONNOUSERSITE +PYTHONPATH +RANLIB +READELF +SIZE +SSL_CERT_FILE +STRINGS +STRIP +SYSTEM_CERTIFICATE_PATH +TEMP +TEMPDIR +TMP +TMPDIR +VIRTUAL_ENV +VIRTUAL_ENV_PROMPT +XML_CATALOG_FILES +_PYTHON_HOST_PLATFORM +_PYTHON_SYSCONFIGDATA_NAME +__structuredAttrs +buildInputs +buildPhase +builder +cmakeFlags +configureFlags +depsBuildBuild +depsBuildBuildPropagated +depsBuildTarget +depsBuildTargetPropagated +depsHostHost +depsHostHostPropagated +depsTargetTarget +depsTargetTargetPropagated +doCheck +doInstallCheck +mesonFlags +name +nativeBuildInputs +out +outputs +patches +phases +postShellHook +postVenvCreation +preferLocalBuild +propagatedBuildInputs +propagatedNativeBuildInputs +shell +shellHook +stdenv +strictDeps +system +venvDir ~GI_TYPELIB_PATH ~PATH ~XDG_DATA_DIRS
+```
+
+You can further validate that everything is set up correctly by running 
+
+
+```
+pip freeze
+```
+
+You should see a list of packages similar to those listed below:
+
+```
+Babel==2.13.1
+beautifulsoup4==4.12.2
+black==23.11.0
+Brotli==1.1.0
+brotlicffi==1.1.0.0
+certifi==2023.7.22
+cffi==1.16.0
+chardet==5.2.0
+charset-normalizer==3.2.0
+click==8.1.7
+colorama==0.4.6
+cssselect2==0.7.0
+defusedxml==0.7.1
+fonttools==4.42.1
+ghp-import==2.1.0
+gitdb==4.0.11
+GitPython==3.1.40
+griffe==0.38.0
+html5lib==1.1
+idna==3.4
+Jinja2==3.1.2
+libsass==0.22.0
+lxml==4.9.3
+Markdown==3.5.1
+MarkupSafe==2.1.3
+mdx-gh-links==0.3.1
+mergedeep==1.3.4
+mkdocs==1.5.3
+mkdocs-autorefs==0.5.0
+mkdocs-enumerate-headings-plugin==0.6.1
+mkdocs-git-revision-date-localized-plugin==1.2.1
+mkdocs-material==9.4.14
+mkdocs-material-extensions==1.3.1
+mkdocs-pdf-export-plugin==0.5.10
+mkdocs-redirects==1.2.1
+mkdocs-video==1.5.0
+mkdocs-with-pdf==0.9.3
+mkdocstrings==0.24.0
+mkdocstrings-python==1.7.5
+mypy-extensions==1.0.0
+olefile==0.46
+packaging==23.2
+paginate==0.5.6
+pathspec==0.11.2
+Pillow==10.1.0
+platformdirs==4.1.0
+pycairo==1.24.0
+pycparser==2.21
+pydyf==0.8.0
+Pygments==2.17.2
+PyGObject==3.46.0
+pymdown-extensions==10.5
+pyphen==0.14.0
+python-dateutil==2.8.2
+pytz==2023.3.post1
+PyYAML==6.0.1
+pyyaml_env_tag==0.1
+regex==2023.10.3
+requests==2.31.0
+shortuuid==1.0.11
+six==1.16.0
+smmap==5.0.1
+soupsieve==2.5
+tinycss2==1.2.1
+urllib3==2.0.7
+watchdog==3.0.0
+weasyprint==60.1
+webencodings==0.5.1
+zopfli==0.2.3
+```
+
+
+## Workflow 1: HTML Static Web Site
+
+In this workflow, we will build the static website created by our
+documentation, and then use the development server provided by mkdocs to view
+the site. We assume as a starting point that you have not yet run nix-shell:
+
+```
+nix-shell
+./create-mkdocs-html-config.sh
+./build-docs-html.sh
+mkdocs serve
+```
+
+By default the mkdocs server will publish the site on your localhost, port 8000
+at http://127.0.0.1:8000/
+
+In your web browser you can then peruse the generated site. To stop the server,
+return to your shell and press ``Crtl-c``.
+
+If you want to rebuild your docs after making some edits / corrections, you can
+then just run the last two steps again:
+
+```
+./build-docs-html.sh
+mkdocs serve
+```
+
+Alternatively, just leave the server running, make your edits as needed and
+mkdocs will rebuild the site whenever you make a change.
+
+## Workflow 2: PDF Generated Documentation
+
+This workflow is almost identical to workflow 1, except in this case, we will
+build the PDF documentation, and then use the development server to rebuild the
+PDF as needed. We assume as a starting point that you have not yet run
+nix-shell:
+
+```
+nix-shell
+./create-mkdocs-pdf-config.sh
+./build-docs-pdf.sh
+mkdocs serve
+```
+
+By default the mkdocs serve will generate the PDF into the ``pdfs`` folder as
+file [QPLUS.pdf](pdfs/CPLUS.pdf).
+
+In your PDF viewer you can then peruse the generated document. To stop the server,
+return to your shell and press ``Crtl-c``.
+
+If you want to rebuild your docs after making some edits / corrections, you can
+then just run the last two steps again:
+
+```
+./build-docs-pdf.sh
+mkdocs serve
+```
+
+Alternatively, just leave the server running, make your edits as needed and
+mkdocs will rebuild the PDF whenever you save a change.
+

docs/build-docs-html.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+# This is only intended for local
+# testing. See github workflows for 
+# how this build is automated.
+
+# this will create mkdocs.yml
+./create-mkdocs-html-config.sh
+# and this will build the html site
+mkdocs build

docs/build-docs-pdf.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+# This is only intended for local
+# testing. See github workflows for 
+# how this build is automated.
+
+# this will create mkdocs.yml
+./create-mkdocs-pdf-config.sh
+# and this will build the PDF document
+mkdocs build

docs/clean.sh

@@ -0,0 +1,6 @@
+#! /usr/bin/env bash
+
+rm -rf .venv
+rm -rf site
+rm -rf __pycache__
+

docs/create-mkdocs-html-config.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+# This script will assemble a mkdocs.yml
+# file with plugins section suitable for 
+# html site generation.
+
+# This script is used both in manual
+# site compilation (via build-docs-html.sh)
+# and via the github workflow for 
+# publishing the site to github pages
+# .github/workflows/BuildMKDocsAndPublishToGithubPages.yml
+
+cat mkdocs-base.yml > mkdocs.yml
+cat mkdocs-html.yml >> mkdocs.yml

docs/create-mkdocs-pdf-config.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+# This script will assemble a mkdocs.yml
+# file with plugins section suitable for 
+# PDF site generation.
+
+# This script is used both in manual
+# site compilation (via build-docs-html.sh)
+# and via the github workflow for 
+# publishing the site to github pages
+# .github/workflows/CompileMKDocsToPDF.yml
+
+cat mkdocs-base.yml > mkdocs.yml
+cat mkdocs-pdf.yml >> mkdocs.yml
+# This is a kludge: I could not figure out 
+# how to reference image resources using a relative path in the scss...
+cat templates/styles.scss.templ | sed "s?\[BASE_FOLDER\]?$PWD?g" > templates/styles.scss

docs/default.nix

@@ -0,0 +1,61 @@
+with import <nixpkgs> { };
+
+let
+  # For packages pinned to a specific version
+  pinnedHash = "933d7dc155096e7575d207be6fb7792bc9f34f6d"; 
+  pinnedPkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/${pinnedHash}.tar.gz") { };
+  pythonPackages = pinnedPkgs.python3Packages;
+in pkgs.mkShell rec {
+  name = "impurePythonEnv";
+  venvDir = "./.venv";
+  buildInputs = [
+    # A Python interpreter including the 'venv' module is required to bootstrap
+    # the environment.
+    pythonPackages.python
+
+    # This executes some shell code to initialize a venv in $venvDir before
+    # dropping into the shell
+
+    # For PDF production  in mkdocs
+    pythonPackages.venvShellHook
+    python311Packages.weasyprint
+    pinnedPkgs.cairo
+    pinnedPkgs.pango
+    pinnedPkgs.gdk-pixbuf
+    pinnedPkgs.glib
+    pinnedPkgs.gtk2
+    # Those are dependencies that we would like to use from nixpkgs, which will
+    # add them to PYTHONPATH and thus make them accessible from within the venv.
+    pythonPackages.requests
+    pythonPackages.pygobject3
+    # Doesnt work properly
+    #python311Packages.cffi
+    pinnedPkgs.gobject-introspection 
+    pinnedPkgs.gtk3
+    pinnedPkgs.taglib
+    pinnedPkgs.openssl
+    pinnedPkgs.git
+    pinnedPkgs.libxml2
+    pinnedPkgs.libxslt
+    pinnedPkgs.libzip
+    pinnedPkgs.zlib
+    pinnedPkgs.gnused
+    pinnedPkgs.rpl
+  ];
+
+  # Run this command, only after creating the virtual environment
+  postVenvCreation = ''
+    unset SOURCE_DATE_EPOCH
+    pip install -r requirements.txt 
+  '';
+
+  shellHook = ''
+  '';
+  # Now we can execute any commands within the virtual environment.
+  # This is optional and can be left out to run pip manually.
+  postShellHook = ''
+    # allow pip to install wheels
+    unset SOURCE_DATE_EPOCH
+  '';
+
+}