Developing everyapp.bootstrap can be great fun. In order to keep things manageable, the source code is stored in a Mercurial repository and a consistent development environment has been built (using everyapp.bootstrap, of course). Additionally, the documentation, in it’s various formats, is all generated from a single set of source files that are readable in plain text form as well.
In order to get started hacking, whether it be on the code or the documentation, you need to clone the repository and bootstrap the development environment. See below for details on how to do both. After that you are free to make your changes and submit patches as desired.
Happy hacking![1]
everyapp.bootstrap‘s source code is stored in a Mercurial repository on Bitbucket. To check out the latest revision from the repository, run:
hg clone https://bitbucket.org/everyapp/bootstrap everyapp.bootstrap
Once you have cloned the repository (see above), you need to bootstrap the development environment before you can start hacking on the code effectively. To do so, run these commands:
cd everyapp.bootstrap
python bootstrap.py
source bin/activate
On Windows, replace the last line above with:
Scripts\activate.bat
Or, to just install it directly, run:
cd everyapp.bootstrap
python setup.py install
While the plain text version of the documentation provides most of the relevant information, the full documentation is best experienced in one of the generated formats. The following generated formats are currently supported:
You can view the generated documentation online, or you can generate the above formats by following the instructions below.
Note
To generate the documentation, you must first set up the development environment (virtualenv environment with all development dependencies already installed). The instructions and code assume that you are working from within one. See above for instructions on how to set one up.
Note
In addition to the tools automatically included in the development environment, you will also need to have Latex installed in order to generate the PDF format. See the Sphinx documentation for details. If you do not have Latex installed, or do not want the PDF version, just omit the latexpdf option or command from the instructions below.
On POSIX systems (Linux, Mac, etc.), run the following commands:
cd doc/source
make clean html epub latexpdf man
On Windows systems, run the following:
cd doc\source
make clean
make html
make epub
make latexpdf
make man
On all platforms the generated documentation will be in the doc/build directory.
This project occasionally produces release distributions. These are stable versions of the code with specific version numbers. Additionally, sometimes it is useful to produce development releases. The instructions below outline how to create release distributions.
To make a release:
Update the release date and add important changes in the doc/NEWS.txt file. Commit the changes.
Proof read and spell check all source code and documentation. Commit the changes.
Tag the release using the version number as the tag. e.g. v0.3.1.
Generate the change log with:
hg log --style changelog > doc/ChangeLog.txt
If running on a POSIX machine (Linux, Mac), fix the line endings with:
unix2dos doc/ChangeLog.txt
If this is an official release and not a development release, run:
python setup.py release sdist
Otherwise, run:
python setup.py sdist
Test the generated source distribution in the dist/ directory.
Upload to PyPI by running:
python setup.py [release] sdist register upload
Delete the generated doc/ChangeLog.txt file.
Generate the documentation by following Generating the Documentation.
Copy the PDF and EPUB version into the HTML version by running:
cd doc/build
cp latex/everyapp.bootstrap-<version>.pdf html/_static/everyapp.bootstrap.pdf
cp epub/everyapp.bootstrap-<version>.epub html/_static/everyapp.bootstrap.epub
Or on Windows, run:
cd doc\build
copy latex\everyapp.bootstrap-<version>.pdf html\_static\everyapp.bootstrap.pdf
copy epub\everyapp.bootstrap-<version>.epub html\_static\everyapp.bootstrap.epub
Upload the documentation by running:
python setup.py upload_docs
Increase version in setup.py for the next release. Make sure this is consistent with Semantic Versioning 1.0.0.
Add a new section to doc/NEWS.txt for the next release.
Commit the changes.
Remember to push all changesets to Bitbucket.
Update your development environment by running:
python setup.py develop
Footnotes
| [1] | This expression is most famously used by Richard M. Stallman. |