Developing

Installation

One is encouraged to develop inside a virtual environment.

Make sure the the frontend development environment is properly set.

cd template_dev
npm install -g gulp
npm install

To immediately reflect code change, install NGCloud under develop mode:

python setup.py develop
# or
pip install -e .[all]

Extra dependencies are required to enable syntax checking:

pip install -r requirements_dev.txt

Building frontend CSS/JS

Javascript and CSS for builtin templates are built from CoffeeScript and Stylus sources under template_dev/src, which provide succinct and maintainable syntax.

From a frontend developer’s point of view, their building process has been well-defined in gulpfile.coffee and been managed by Gulp.js,

# under template_dev
gulp coffee     # generate js files under ./js
gulp stylus     # generate css files under ./css
gulp            # generate both js and css

gulp release    # generate both js and css under ngcloud/pipe/report/static

gulp clean

From a Python developer’s point of view, learning the frontend knowledge requires great effort. So these details have been hidden inside setup.py.

Every time source are updated and new CSS/JS build is required, run

python setup.py build_frontend

This will have the same effect as gulp release.

Warning

Never modified generated CSS/JS directly. They will be overwritten without warning everytime building being triggered

Automated building

When developing templates or writing docs, one may constantly needs to run make html or ngreport to see the changed outputs. But that is sometimes demanding so here is some trick for automated building when sources change.

Requires watchdog. Take building docs as example, under docs run:

watchmedo shell-command \
    --interval 3 --wait --drop \
    --recursive --patterns="*.rst" \
    --command='make html' .

Then watchdog will monitor the doc folder and run make html when any rst file changes.

Frontend CSS/JS

There are plenty of ways to watch their source change. Under template_dev run:

gulp watch  # it ingores events of new file created
make        # below it calls the watchmedo then calls gulp

Deploy to PyPI

Original version:

python setup.py egg_info -RDb '' build_frontend sdist --formats="gztar,zip" bdist_wheel --universal
python setup.py egg_info -RDb '' register
twine upload dist/*

Simplified version:

python setup.py release sdist bdist_wheel   # check output
python setup.py release register
twine upload dist/*