diff --git a/custom_theme b/custom_theme deleted file mode 100644 index 800384a..0000000 --- a/custom_theme +++ /dev/null @@ -1 +0,0 @@ -mk_doc_ultra/custom_theme \ No newline at end of file diff --git a/custom_theme b/custom_theme new file mode 120000 index 0000000..e0d7318 --- /dev/null +++ b/custom_theme @@ -0,0 +1 @@ +./mk_doc_ultra/custom_theme/ \ No newline at end of file diff --git a/docs/environment/makefile.png b/docs/environment/makefile.png new file mode 100644 index 0000000..23768a0 Binary files /dev/null and b/docs/environment/makefile.png differ diff --git a/docs/environment/makefiles.md b/docs/environment/makefiles.md index bb96367..8d13e3a 100644 --- a/docs/environment/makefiles.md +++ b/docs/environment/makefiles.md @@ -1 +1,31 @@ # Makefiles + +Development has many tasks that have configuration options and stages. +Building documentation, running test suites, even building the virtual +environment, all can have many options. Remembering the right order, +combination and so on takes up valuable head-space for a developer and +when you send your code to someone else, represents a lot of things to +explain and/or document. It is useful, then, to automate these kinds +of tasks. + +There are many ways to do this, but a common one is to use Makefiles. + +Makefiles can be hugely complex, but we are not going to get into +anything too complex the important thing to know is that when we +provide you with a Makefile, you can find out what it can do by +examining the file. + +Here, I'm displaying the contents of the Makefile using `cat`: + +![Contents of a Makefile](./makefile.png#screenshot) + + +Lines that start with a word and a colon (`build:`) for example, are +the start of the directives that can be used. + +`make build` will activate it. + +In many shells, if you type just `make` and then press tab, you can +get a list of options. The provided VM has this feature: + +![Example of tab-completion of `make` directives](./maketab.png#screenshot) diff --git a/docs/environment/maketab.png b/docs/environment/maketab.png new file mode 100644 index 0000000..0b88fe3 Binary files /dev/null and b/docs/environment/maketab.png differ diff --git a/docs/environment/makevenv.png b/docs/environment/makevenv.png new file mode 100644 index 0000000..6e45153 Binary files /dev/null and b/docs/environment/makevenv.png differ diff --git a/docs/environment/pip.md b/docs/environment/pip.md index 226715d..54e45e0 100644 --- a/docs/environment/pip.md +++ b/docs/environment/pip.md @@ -1 +1,21 @@ # Pip + +Pip is a package installer that allows you to access the huge number +of packages available for python. + +The documentation is very good: + +## Pip Tips + +1. If you have Python 2.7 and Python 3 installed, use `pip3` to make + sure you are using the correct version of pip. Generally, use + `pip3` anyway unless your system has only one install and it is + aliased to `pip`. +2. Searching: use `pip3 search X` to search for packages +3. Installing: use `pip3 install X` to install X + + +## Check your understanding + +??? question "How would you install the 'colored' package?" + Just use `pip3 install colored`. ![Example of installing the 'colored' package](./pip3colored.png#screenshot) diff --git a/docs/environment/pip3colored.png b/docs/environment/pip3colored.png new file mode 100644 index 0000000..ab65ffc Binary files /dev/null and b/docs/environment/pip3colored.png differ diff --git a/docs/environment/venv.md b/docs/environment/venv.md index f6540eb..a224787 100644 --- a/docs/environment/venv.md +++ b/docs/environment/venv.md @@ -1 +1,58 @@ # Virtual Environments + +With Python being very common now, different libraries and versions +can be required by different programs. Different operating systems +have dealt with this kind of issue in different ways in the +past,usually by trying to share libraries across the whole system[^4] +but with modern development the goal is portability and ease of +development rather than raw efficiency. Python programmers have the +option of using **Virtual Environments** for their software projects, +in which the libraries are installed specifically for their software, +with exactly the right versions, and even the python interpreter is +fixed and separate from the system-wide interface. + +Below is the quick-start guide to using virtual environments. Detailed +information is available here: + + +The quick-start expects a Linux environment, but this can also be used +on Windows with slight changes. + +## Creating a Virtual Environment + +The environment is all contained within a directory. So if your +project is in `~/myCodez` and we create a virtual environment called +`venv`, then it will probably be best placed in `~/myCodez/venv`. + +From the `~/myCodez` directory, use `python3 -m venv venv`. In the +example below, you can see the result. + +![Creating a virtual environment called "venv"](./makevenv.png#screenshot) + +Inside that directory are now a complete set of files for a separate python environment. + +## Activating a Virtual Environment + +While in your source directory, type `. ./venv/bin/activate` (note the +leading dot) to activate it. This changes your environment variables +so if you install modules, they go in your virtual environment, when +you run `python`, it is running from the version in the virtual +environment, etc. + +You can verify this using `which`[^1]. + +![Activating a virtual environment](./venvactivate.png#screenshot) + +As you can see from the screenshot, if you're using the provided VM +then the default shell is `zsh` and it is configured to show +information about whether you're in an activated virtual environment[^2]. + +## Check Your Understanding + +Make sure you can recreate the example above, in which a virtual +environment is created and activated. + + +[^1]: A command that tells you where an executable in the path is. `which bash` gives `/bin/bash`, for example. + +[^2]: And git status, better tab-completion, etc. diff --git a/docs/environment/venvactivate.png b/docs/environment/venvactivate.png new file mode 100644 index 0000000..1a15c94 Binary files /dev/null and b/docs/environment/venvactivate.png differ diff --git a/mkdocs.yml b/mkdocs.yml index b8bceaa..e5680f8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,9 +6,9 @@ nav: - 'Development Environment': - 'Introduction': 'environment/index.md' - 'Files and Execution': ./environment/files.md - - 'TODO - Pip': ./environment/pip.md - - 'TODO - Virtual Environments': ./environment/venv.md - - 'TODO - Makefiles': ./environment/makefiles.md + - 'Pip': ./environment/pip.md + - 'Virtual Environments': ./environment/venv.md + - 'Makefiles': ./environment/makefiles.md - 'Values and Types': 'values-and-types/README.md' - 'Evaluation and Operators': 'evaluationandoperators/README.md' @@ -64,13 +64,13 @@ plugins: theme: name: material - custom_dir: 'mk_doc_ultra/' ## Labels a custom directory that can contain modifications to the theme, js and css are auto loaded from here. + #custom_dir: 'mk_doc_ultra/' ## Labels a custom directory that can contain modifications to the theme, js and css are auto loaded from here. logo: 'images/logo.svg' palette: primary: 'indigo' accent: 'indigo' scheme: preference - # custom_dir: custom_theme + custom_dir: custom_theme # include_dir: 'mk_doc_ultra/' ## don't know what it does but there is good syntax here and no errors