Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[docs] add maintainers, update contributing instructions (#261)
- Loading branch information
Chad Smith
committed
Nov 4, 2019
1 parent
580f974
commit c6443e9
Showing
5 changed files
with
135 additions
and
74 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,65 +1,132 @@ | ||
| pipx uses [nox](https://pypi.org/project/nox/) for development, continuous integration testing, and automation. | ||
| Thanks for your interest in contributing to pipx! | ||
|
|
||
|
|
||
| ## Dependencies | ||
| pipx uses an automation tool called [nox](https://pypi.org/project/nox/) for development, continuous integration testing, and various tasks. | ||
|
|
||
| `nox` defines tasks or "sessions" in `noxfile.py` which can be run with `nox -s SESSION_NAME`. Session names can be listed with `nox -l`. | ||
|
|
||
| Install nox for pipx development: | ||
| ``` | ||
| pip install --user git+https://github.com/cs01/nox.git@5ea70723e9e6 nox | ||
| ``` | ||
|
|
||
| !!! note | ||
| A specific version of nox must be used for pipx development until [nox issue 233](https://github.com/theacodes/nox/issues/233) is resolved. | ||
|
|
||
|
|
||
| ## Developing pipx | ||
| pipx uses pipx to develop -- it's recursive! But don't worry, it's not that scary. You'll be up in running in no time. You'll also need `make` installed. If you don't have `make`, you can look at pipx's `makefile` to see the what the make targets correspond to). | ||
| Clone pipx, then enter the root of the pipx repository. Run this command to see which commands you can run with nox. | ||
| ``` | ||
| nox -l | ||
| ``` | ||
|
|
||
| To develop `pipx`, first clone the repository. | ||
| You should see some options that look like this | ||
| ``` | ||
| - develop-3.6 | ||
| - develop-3.7 | ||
| - develop-3.8 | ||
| ``` | ||
|
|
||
| Next, run this command which will use the amazing [nox](https://github.com/theacodes/nox) automation framework to set up a virtual environment for each Python version pipx tests against. | ||
| Choose the Python version you want to develop in and run the following commands, modifying with your version as necessary. | ||
| ``` | ||
| make develop | ||
| nox -s develop-3.8 | ||
| source .nox/develop-3.8/bin/activate | ||
| ``` | ||
|
|
||
| A virtual environment with required dependencies is now sandboxed and ready to go in `.nox/develop-3.6` for Python 3.6. Any changes you make to pipx source code will be reflected immediately in the virtual environment inside `.nox/develop-3.6`. | ||
| A virtual environment with required dependencies is now sandboxed and activated! | ||
|
|
||
| So how do you run with that environment? | ||
| Go ahead and make your changes now. You can confirm they still work by running unit tests (see the next section). | ||
|
|
||
| You can either enter the virtual environment with `source .nox/develop-3.6/bin/activate` and run `pipx`, or you can run the development `pipx` directly with `.nox/develop-3.6/bin/pipx`. Either way, it's running directly from the source code you just cloned and will reflect any changes you make. In one case the command is a bit longer but your environment isn't modified. In the other, you can type `pipx` but you have to enter the virtual environment. Whichever you prefer will work fine. Go ahead and make your changes now. | ||
| To leave the environment, type `deactivate`. | ||
|
|
||
| ## Testing pipx locally | ||
| pipx uses the test automation framework [nox](https://github.com/theacodes/nox). Test definitions live in `noxfile.py`. | ||
| Tests are defined as `nox` sessions. You can see all nox sessions with | ||
| ``` | ||
| nox -l | ||
| ``` | ||
|
|
||
| At the time of this writing, the output looks like this | ||
| ``` | ||
| >> nox -l | ||
| Sessions defined in /home/csmith/git/pipx/noxfile.py: | ||
| * tests-3.6 | ||
| * tests-3.7 | ||
| * tests-3.8 | ||
| - cover -> Coverage analysis | ||
| * lint | ||
| * docs | ||
| - develop-3.6 | ||
| - develop-3.7 | ||
| - develop-3.8 | ||
| - build | ||
| - publish | ||
| - watch_docs | ||
| - publish_docs | ||
| ``` | ||
|
|
||
| So to run unit tests in Python3.7, you can run | ||
| ``` | ||
| nox -s tests-3.7 | ||
| ``` | ||
|
|
||
|
|
||
| !!! tip | ||
| You can running a specific unit test by passing arguments to pytest, the test runner pipx uses: | ||
|
|
||
| ``` | ||
| nox -s tests-3.8 -- -k EXPRESSION | ||
| ``` | ||
|
|
||
| Expression can be a test name, such as | ||
|
|
||
| Run tests by exiting any virtual environment, then running | ||
| ``` | ||
| nox -s tests-3.8 -- -k test_uninstall | ||
| ``` | ||
|
|
||
| Coverage errors can usually be ignored when only running a subset of tests. | ||
|
|
||
| To run lint checks, run | ||
| ``` | ||
| make test | ||
| nox -s lint | ||
| ``` | ||
| and so on. | ||
|
|
||
| ## Testing pipx on Continuous Intergration builds | ||
| When you push a new git branch, tests will automatically be run against your code as defined in `.travis`. | ||
|
|
||
| ## Documentation | ||
|
|
||
| Documentation has a couple steps to it, both of which are automated. The first step is to generate markdown files from templates. See the `templates` directory. The generated files will have a header at the top indicating they were generated and shouldn't be manually modified. Modify the templates, not the generated markdown files. | ||
| `pipx` autogenerates API documentation, and also uses templates. | ||
|
|
||
| The second is to compile the markdown files in `docs` with `mkdocs`. | ||
| When updating pipx docs, make sure you are either modifying a file in the `templates` directory, or the `docs` directory. If in the `docs` directory, make sure the file was not autogenerated from the `templates` directory. | ||
|
|
||
| Both of these steps are done in a single build command: | ||
| You can generate the documentation with | ||
| ``` | ||
| make docs | ||
| nox -s docs | ||
| ``` | ||
|
|
||
| To preview changes, including live reloading, open another terminal and run | ||
| ``` | ||
| make watch_docs | ||
| ``` | ||
| This will capture CLI documentation for any pipx argument modifications, as well as generate templates to the docs directory. | ||
|
|
||
| If you make changes to the pipx cli api or any template, regenerate the `.md` files in the `docs` folder: | ||
| To preview changes, including live reloading, open another terminal and run | ||
| ``` | ||
| make docs | ||
| nox -s watch_docs | ||
| ``` | ||
|
|
||
| ### Publishing Doc Changes to GitHub pages | ||
| ``` | ||
| make publish_docs | ||
| nox -s publish_docs | ||
| ``` | ||
|
|
||
| ## Release New `pipx` Version | ||
| To create a new release | ||
|
|
||
| * make sure the changelog is updated | ||
| * update the version of pipx defined in `setup.py` | ||
|
|
||
| Finally, run | ||
| ```bash | ||
| nox -s publish | ||
| nox -s publish_docs | ||
| ``` | ||
| make publish | ||
| ``` | ||
| and don't forget to publish updated documenation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters