Install in developer mode¶
If you are developing the source code of Friendly Sam, you probably want to install it in “develop” mode instead. This has two benefits. First, you get some extra dependencies such as
nose (testing package),
sphinx (documentation package) and
wheel (used for releasing), etc. Second, you won’t have to reinstall the package into your Python site-packages directory every time you change something.
Download the source code
Alternative 1: Download a zip file: https://github.com/sp-etx/friendlysam/archive/master.zip
Alternative 2: If you know git, clone into the repository:
git clone https://github.com/sp-etx/friendlysam.git
You probably want to install Friendly Sam in a virtual environment. Create one and activate it before you take the next step.
Now, to install Friendly Sam in develop mode, do this:
pip install -r develop.txt
If you are on Windows,
pip-installation of some packages will fail if you don’t have a compiler correctly configured. One such example is NumPy. A simple way around it is to install binaries from Christoph Gohlke’s website for the packages that throw errors when you do
pip install -r develop.txt.
Let’s say you are on Windows and download an installer called something like
numpy-MKL-1.9.0.win-amd64-py3.4.exe. Don’t just run the file, because then it will be installed in your “main” Python installation (usually at
C:\Python34). Instead, do this:
Open a command prompt.
Go into your virtual environment (e.g.
vex my_project_name cmd).
(option a) Do this if you have an .exe file:
(option b) Or, if you have a .whl file file, e.g.
numpy-1.9.2+mkl-cp34-none-win_amd64.whl, do this:
pip install numpy-1.9.2+mkl-cp34-none-win_amd64.whl
Make Sphinx documentation¶
If you want to make a very minor change to the documentation, you can actually just edit the source, push to the github repository and magically, the docs will update at readthedocs.org.
However, if you want to edit the docs a lot, you probably want to make test builds on your own machine. In that case, you need to learn about Sphinx. To build the docs, open a command prompt, go to
friendlysam\docsand run the command:
The resulting HTML can be previewed under
Please run the tests before pushing to the master branch.
To run all the tests, including doctests in the source code and doctests in this documentation, go to the project root directory and run:
nosetests --with-doctest --doctest-options=+ELLIPSIS
Releasing Friendly Sam¶
Make sure that the documentation is complete and builds OK. In
Make sure that the tests pass. In project root directory:nosetests --with-doctest --doctest-options=+ELLIPSIS
Make sure the changelog is up-to-date.
version.txtwith the next semantic version number: http://semver.org/
Commit and push to
masterbranch. Then tag the release and push the tag:git tag -a vX.Y.Z -m 'Version X.Y.Z' git push origin vX.Y.Z
Releasing to PyPI¶
To put things on PyPI, you have to register on PyPI, and you should register on the test PyPI too:
Make sure that your account is activated. You should get an email from PyPI.
Make sure you are added as a maintainer of the friendlysam repository at PyPI/testPyPI.
Create yourself a file called
.pypircand put it in your home directory. If you are on Windows, the file path should be``C:Usersyourusername.pypirc``. Put the following content in it:[distutils] index-servers = pypi test [pypi] repository:https://pypi.python.org/pypi username:your_pypi_username [test] repository:https://testpypi.python.org/pypi username:your_testpypi_username
(Windows users) For Windows, there is a nice
pypi.batyou can use.
To register info about the package on PyPI, first push to the PyPI test site:pypi.bat register test
You will be asked for your PyPI test password. Make sure it turned out as you wanted. Then do the real thing:pypi.bat register pypi
To build and upload the distribution, do this:pypi.bat upload test
Twine will upload to PyPI and ask you for username and password. Check on the test site that everything is OK. You can also run
pip install ...from the test repo to be sure. Then upload the package to the real repo by running:pypi.bat upload pypi
- (Linux/Mac users) You can easily translate
pypi.batinto a bash script. Please do so and contribute it to the repository!