Building

This part of the documentation covers working with the Source Code of VSGAN, or it’s documentation.

Preparing your Environment

Requirements

  • Python on a supported version, see pyproject.toml’s Python dependency line.

  • Pip on v19.0 or newer (Pip with PEP-517 support).

  • Poetry on the latest version.

Configuring Poetry

I recommend doing poetry config virtualenvs.in-project true to simplify the virtual-env creation process. This also helps solve issues related to unnecessary venv re-creations, duplicate files, and caching.

Getting the Source Code

Simply download the source code any way you wish, I recommend with git. You can use git checkout to go to any point of the code, switch branches, or make new ones.

$ git clone https://github.com/rlaphoenix/VSGAN
$ cd VSGAN

The rest of this document will assume you have a terminal at the folder of source code.

Installing Dependencies

As well as specific dev-environment dependencies which we have just gone through, you also need to install the normal dependencies that VSGAN needs.

  1. Install all of the Software Requirements from the Installation guide.

  2. Install the Python-based dependencies with poetry install.

  3. If you want to build the docs locally, install the extra dependencies with poetry install -E docs.

Your environment is now prepared, you can now go ahead and work on the Source Code or Documentation.

Installing from Source Code

Warning

There are some caveats when installing from Source Code:

  1. Source code may have changes that are not yet tested or stable, and may have regressions.

  2. Only install from source code if you have a reason. E.g., to test changes.

If you wish to install from Source Code to your machine, outside of the poetry virtual-env that is used for development:

$ git clone https://github.com/rlaphoenix/VSGAN
$ cd VSGAN
$ python -m pip install --user .

You may also follow the steps below to build a distribution wheel which you can then use instead, which has the added benefit of being shareable for quick installation.

However, if you would like to install it within the development virtual-env the poetry install call made earlier is done in editable mode. Meaning any change you make and then save (with some exceptions) will be immediately reflected in the installed site-packages directory of the venv.

Building distribution files

Distribution files are builds (wheel) or source-code blobs (sdist) for quick and easy sharing and installation with the changes made intact. These wheel files are the same ones used when installing VSGAN and other software via pip.

To make a distribution file. E.g., for a new release version. It’s as simple as one call, poetry build. This will build a wheel and sdist into the directory /dist.

The built wheel can then be installed using pip, e.g.,:

$ pip install dist/vsgan-1.4.0-py3-none-any.whl

Building the Documentation

You must have the extra documentation dependencies installed, poetry install -E docs.

Working with the documentation from there can be done in many ways, like with sphinx-autobuild to have it auto-reload changes, or with Visual Studio Code which can have a auto-reloading preview on the right as you work on the documentation. Its how I’ve written what you are reading right now!

If you simply want to just build it to a HTML directory that you can then view in your browser locally:

$ cd docs
$ .\make html

The built documentation will then be in /docs/_build, with the index.html at /docs/_build/html/index.html.