Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Finished content for pip, makefile, env, etc.
  • Loading branch information
csx239 committed Sep 16, 2020
1 parent 5372ceb commit e3b8d02
Show file tree
Hide file tree
Showing 10 changed files with 113 additions and 6 deletions.
1 change: 0 additions & 1 deletion custom_theme

This file was deleted.

1 change: 1 addition & 0 deletions custom_theme
Binary file added docs/environment/makefile.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
30 changes: 30 additions & 0 deletions 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)
Binary file added docs/environment/maketab.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/environment/makevenv.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
20 changes: 20 additions & 0 deletions 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: <https://pip.pypa.io/en/stable/quickstart/>

## 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)
Binary file added docs/environment/pip3colored.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
57 changes: 57 additions & 0 deletions 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:
<https://docs.python.org/3/tutorial/venv.html>

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.
Binary file added docs/environment/venvactivate.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
10 changes: 5 additions & 5 deletions mkdocs.yml
Expand Up @@ -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'
Expand Down Expand Up @@ -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


Expand Down

0 comments on commit e3b8d02

Please sign in to comment.