Install Morepath for development¶
First make sure you have virtualenv installed for Python 3.5.
Now create a new virtualenv somewhere for Morepath development:
$ virtualenv /path/to/ve_morepath
You should also be able to recycle an existing virtualenv, but this guarantees a clean one. Note that we skip activating the environment here, as this is just needed to initially bootstrap the Morepath buildout.
Clone Morepath from github and go to the morepath directory:
$ git clone email@example.com:morepath/morepath.git $ cd morepath
Now we need to run bootstrap.py to set up buildout, using the Python from the virtualenv we’ve created before:
$ /path/to/ve_morepath/bin/python bootstrap.py
This installs buildout, which can now set up the rest of the development environment:
This downloads and installs various dependencies and tools. The
commands you run in
bin are all restricted to the virtualenv you
set up before. There is therefore no need to refer to the virtualenv
once you have the development environment going.
Running the tests¶
You can run the tests using py.test. Buildout has installed it for
you in the
bin subdirectory of your project:
$ bin/py.test morepath
To generate test coverage information as HTML do:
$ bin/py.test morepath --cov morepath --cov-report html
You can then point your web browser to the
in the project directory and click on modules to see detailed coverage
To do pyflakes and pep8 checking do:
$ bin/flake8 morepath
The buildout installs radon. This is a tool that can check various measures of code complexity.
To check for cyclomatic complexity (excluding the tests):
$ bin/radon cc morepath -e "morepath/tests*"
To filter for anything not ranked
$ bin/radon cc morepath --min B -e "morepath/tests*"
And to see the maintainability index:
$ bin/radon mi morepath -e "morepath/tests*"
Running the documentation tests¶
The documentation contains code. To check these code snippets, you can run this code using this command:
$ bin/sphinxpython bin/sphinx-build -b doctest doc doc/build/doctest
If you have Make installed, buildout generates for you a Makefile in
doc/build that you can use:
$ (cd doc/build; make doctest)
Throughout this documentation, examples are using the Python 3.5 syntax.
Building the HTML documentation¶
To build the HTML documentation (output in
In some cases we have to make changes that break compatibility and
break user code. We mark these in
using breaking change, deprecated or removed.
These entries should explain the change, and also tell the user what to do to upgrade their code. Do include an before/after code example as that makes it much easier, even if it’s a simple import change.
We like to keep things moving and reserve the right to introduce
breaking changes. When we do make a breaking change it should be
marked clearly in
CHANGES.txt (CHANGES) with a Breaking
If it is not a great burden we use deprecations. Morepath in this case retains the old APIs but issues a deprecation warning. See Upgrading to a new Morepath version for the notes for end-users concerning this. Here is the deprecation procedure for developers:
Add a Deprecated entry in
CHANGES.txtthat describes what to do, as in a breaking change.
Issue a deprecation warning in the code that is deprecated.
**Deprecated**entry in the docstring of whatever got deprecated with a brief comment on what to do.
Put an issue labeled
remove deprecationin the tracker for one release milestone after the upcoming release that states we should remove the deprecation. Create the milestone if needed.
This way we don’t maintain deprecated code and their warnings indefinitely – one release later we remove the backwards compatibility code and deprecation warnings.
Once we go and remove code, we repeat the information on what to do in a new Removed* entry in
CHANGES.txt; treat it just like Breaking change and recycle the text written for the previous Deprecated entry for the stuff we’re now removing.