Skip to content

Commit

Permalink
📝 Add docs for virtual environments, environment variables, and updat…
Browse files Browse the repository at this point in the history 
…e contributing
  • Loading branch information
@tiangolo
tiangolo committed Aug 23, 2024
1 parent 29d1d1f commit 482e64f
Show file tree
Hide file tree
Showing 9 changed files with 1,262 additions and 190 deletions.
2 changes: 2 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ The key features are:

## Installation

Create and activate a <a href="https://typer.tiangolo.com/virtual-environments/" class="external-link" target="_blank">virtual environment</a> and then install **Typer**:

<div class="termy">

```console
Expand Down
208 changes: 61 additions & 147 deletions docs/contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,197 +4,144 @@ First, you might want to see the basic ways to [help Typer and get help](help-ty

## Developing

If you already cloned the repository and you know that you need to deep dive in the code, here are some guidelines to set up your environment.
If you already cloned the <a href="https://github.com/fastapi/typer" class="external-link" target="_blank">typer repository</a> and you want to deep dive in the code, here are some guidelines to set up your environment.

### Virtual environment with `venv`
### Virtual Environment

You can create a virtual environment in a directory using Python's `venv` module:
Follow the instructions to create and activate a [virtual environment](virtual-environments.md){.internal-link target=_blank} for the internal code of `fastapi`.

<div class="termy">

```console
$ python -m venv env
```

</div>

That will create a directory `./env/` with the Python binaries and then you will be able to install packages for that isolated environment.

### Activate the environment
### Install Requirements Using `pip`

Activate the new environment with:

//// tab | Linux, macOS
After activating the environment, install the required packages:

<div class="termy">

```console
$ source ./env/bin/activate
$ pip install -r requirements.txt

---> 100%
```

</div>

////

//// tab | Windows PowerShell

<div class="termy">

```console
$ .\env\Scripts\Activate.ps1
```
It will install all the dependencies and your local Typer in your local environment.

</div>
### Using your Local Typer

////
If you create a Python file that imports and uses Typer, and run it with the Python from your local environment, it will use your cloned local Typer source code.

//// tab | Windows Bash
And if you update that local Typer source code when you run that Python file again, it will use the fresh version of Typer you just edited.

Or if you use Bash for Windows (e.g. <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
That way, you don't have to "install" your local version to be able to test every change.

<div class="termy">
/// note | "Technical Details"

```console
$ source ./env/Scripts/activate
```
This only happens when you install using this included `requirements.txt` instead of running `pip install typer` directly.

</div>
That is because inside the `requirements.txt` file, the local version of Typer is marked to be installed in "editable" mode, with the `-e` option.

////
///

To check it worked, use:
### Format

//// tab | Linux, macOS, Windows Bash
There is a script that you can run that will format and clean all your code:

<div class="termy">

```console
$ which pip

some/directory/typer/env/bin/pip
$ bash scripts/format.sh
```

</div>

////
It will also auto-sort all your imports.

## Tests

//// tab | Windows PowerShell
There is a script that you can run locally to test all the code and generate coverage reports in HTML:

<div class="termy">

```console
$ Get-Command pip

some/directory/typer/env/bin/pip
$ bash scripts/test-cov-html.sh
```

</div>

////

If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉

/// tip

Every time you install a new package with `pip` under that environment, activate the environment again.

This makes sure that if you use a terminal program installed by that package (like `flit`), you use the one from your local environment and not any other that could be installed globally.
This command generates a directory `./htmlcov/`, if you open the file `./htmlcov/index.html` in your browser, you can explore interactively the regions of code that are covered by the tests, and notice if there is any region missing.

///
## Docs

### Flit
First, make sure you set up your environment as described above, that will install all the requirements.

**Typer** uses <a href="https://flit.readthedocs.io/en/latest/index.html" class="external-link" target="_blank">Flit</a> to build, package and publish the project.
### Docs live

After activating the environment as described above, install `flit`:
During local development, there is a script that builds the site and checks for any changes, live-reloading:

<div class="termy">

```console
$ pip install flit
$ python ./scripts/docs.py live

---> 100%
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes
```

</div>

Now re-activate the environment to make sure you are using the `flit` you just installed (and not a global one).
It will serve the documentation on `http://127.0.0.1:8008`.

And now use `flit` to install the development dependencies:
That way, you can edit the documentation/source files and see the changes live.

//// tab | Linux, macOS
/// tip

<div class="termy">
Alternatively, you can perform the same steps that scripts does manually.

```console
$ flit install --deps develop --symlink
Go into the docs director at `docs/`:

---> 100%
```console
$ cd docs/
```

</div>

////

//// tab | Windows

If you are on Windows, use `--pth-file` instead of `--symlink`:

<div class="termy">
Then run `mkdocs` in that directory:

```console
$ flit install --deps develop --pth-file

---> 100%
$ mkdocs serve --dev-addr 8008
```

</div>

////

It will install all the dependencies and your local Typer in your local environment.

#### Using your local Typer
///

If you create a Python file that imports and uses Typer, and run it with the Python from your local environment, it will use your local Typer source code.
#### Typer CLI (optional)

And if you update that local Typer source code, as it is installed with `--symlink` (or `--pth-file` on Windows), when you run that Python file again, it will use the fresh version of Typer you just edited.
The instructions here show you how to use the script at `./scripts/docs.py` with the `python` program directly.

That way, you don't have to "install" your local version to be able to test every change.
But you can also use <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>, and you will get autocompletion in your terminal for the commands after installing completion.

### Format

There is a script that you can run that will format and clean all your code:
If you install Typer CLI, you can install completion with:

<div class="termy">

```console
$ bash scripts/format.sh
$ typer --install-completion

zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.
```

</div>

It will also auto-sort all your imports.

For it to sort them correctly, you need to have Typer installed locally in your environment, with the command in the section above using `--symlink` (or `--pth-file` on Windows).

### Format imports

There is another script that formats all the imports and makes sure you don't have unused imports:
### Docs Structure

<div class="termy">

```console
$ bash scripts/format-imports.sh
```
The documentation uses <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.

</div>
And there are extra tools/scripts in place in `./scripts/docs.py`.

As it runs one command after the other and modifies and reverts many files, it takes a bit longer to run, so it might be easier to use `scripts/format.sh` frequently and `scripts/format-imports.sh` only before committing.
/// tip

## Docs
You don't need to see the code in `./scripts/docs.py`, you just use it in the command line.

The documentation uses <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.
///

All the documentation is in Markdown format in the directory `./docs`.

Expand All @@ -206,45 +153,12 @@ In fact, those blocks of code are not written inside the Markdown, they are Pyth

And those Python files are included/injected in the documentation when generating the site.

### Docs for tests
### Docs for Tests

Most of the tests actually run against the example source files in the documentation.

This helps making sure that:
This helps to make sure that:

* The documentation is up to date.
* The documentation is up-to-date.
* The documentation examples can be run as is.
* Most of the features are covered by the documentation, ensured by test coverage.

During local development, there is a script that builds the site and checks for any changes, live-reloading:

<div class="termy">

```console
$ bash scripts/docs-live.sh

<span style="color: green;">[INFO]</span> - Building documentation...
<span style="color: green;">[INFO]</span> - Cleaning site directory
<span style="color: green;">[INFO]</span> - Documentation built in 2.74 seconds
<span style="color: green;">[INFO]</span> - Serving on http://127.0.0.1:8008
```

</div>

It will serve the documentation on `http://127.0.0.1:8008`.

That way, you can edit the documentation/source files and see the changes live.

## Tests

There is a script that you can run locally to test all the code and generate coverage reports in HTML:

<div class="termy">

```console
$ bash scripts/test-cov-html.sh
```

</div>

This command generates a directory `./htmlcov/`, if you open the file `./htmlcov/index.html` in your browser, you can explore interactively the regions of code that are covered by the tests, and notice if there is any region missing.
Loading

0 comments on commit 482e64f

Please sign in to comment.