diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..69b6b4b --- /dev/null +++ b/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]() 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/timlinux/QGISAnimationWorkbench.git +``` + +or + +``` +git clone git@github.com:timlinux/QGISAnimationWorkbench.git +``` + +### Open the project in your terminal + +Open your favourite terminal and enter into this documentation folder: + +``` +cd QGISAnimationWorkbench/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/QGISAnimationWorkbench/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 [QGISAnimationWorkbench.pdf](pdfs/QGISAnimationWorkbench.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. + diff --git a/docs/default.nix b/docs/default.nix index 1a7f05b..ee1388f 100644 --- a/docs/default.nix +++ b/docs/default.nix @@ -1,7 +1,10 @@ with import { }; let - pythonPackages = python3Packages; + # 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"; @@ -16,28 +19,28 @@ in pkgs.mkShell rec { # For PDF production in mkdocs pythonPackages.venvShellHook python311Packages.weasyprint - cairo - pango - gdk-pixbuf - glib - gtk2 + 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 - gobject-introspection - gtk3 - taglib - openssl - git - libxml2 - libxslt - libzip - zlib - gnused - rpl + 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 diff --git a/docs/pdfs/QGISAnimationWorkbench.pdf b/docs/pdfs/QGISAnimationWorkbench.pdf index c6d47c1..ed79400 100644 Binary files a/docs/pdfs/QGISAnimationWorkbench.pdf and b/docs/pdfs/QGISAnimationWorkbench.pdf differ