Helper Commands for Developing¶
Note
We assume by this point you have installed the project, checked the setup is working (see Step 9: Check Project Setup Works), and also have a basic understanding of the project structure.
The CS Field Guide project uses many systems (Django, Docker, Gulp, etc) to run, so we have written a script for running groups of commands for running the system while developing.
The script is called csfg and can be found in the cs-field-guide folder of the repository.
To run this script, open a terminal window in the directory and enter the following command (you don’t need to enter the $ character, this shows the start of your terminal prompt):
$ ./csfg [COMMAND]
Where [COMMAND] is a word from the list below:
All users of the project (content and technical developers) should become familiar with the following commands:
build¶
Running ./csfg build will build or rebuild the Docker images that are required for the CS Field Guide system.
When you run this command for the first time it can take roughly 15 to 30 minutes depending on your computer and internet speed.
Images are only required to be built once, unless the image specifications change.
clean¶
Running ./csfg clean deletes ‘dangling’ Docker images left over from builds, which will free up hard drive space.
collect_static¶
Running ./csfg collect_static runs the Django collectstatic command to collect static files. It will copy files under the static/ folder into the staticfiles/ folder.
_compilemessages¶
Running ./csfg _compilemessages runs the Django compilemessages command. This runs over .po files and creates .mo files which are optimised for use by gettext.
You will need to run this command after each time you create your message file or each time you make changes to it.
docs¶
Running ./csfg docs will remove any existing documentation and build a fresh copy of the documentation for the CS Field Guide.
end¶
Running ./csfg end will stop any containers which are currently running, this usually takes 10 to 20 seconds.
help¶
Running ./csfg help displays brief help text for the script.
More details for each command can be found on this page.
logs¶
Running ./csfg logs will display the logs for the running systems.
The output is for all logs until the time the command was run, therefore successive calls may display new logs.
To follow logs as they output, enter docker-compose logs --follow.
make_interactive_thumbnails¶
Running ./csfg make_interactive_thumbnails generates the thumbnails for each interactive.
Thumbnails are not generated for uninteractives.
You will need to run the ./csfg collect_static command after for them to appear in the staticfiles/ directory.
The thumbnail for each interactive will be saved under staticfiles/img/interactives/thumbnails/<language-code>/<interactive-slug>.png.
makemessages¶
Running ./csfg makemessages runs the Djanog makemessages command.
This will create message files where each message file represents a single language.
Message files contain all available translation strings and how they should be represented in the given language.
makemigrations¶
Running ./csfg makemigrations runs the Django makemigrations command to create migration files.
migrate¶
Running ./csfg migrate runs the Django migrate command to apply migration files.
reboot_django¶
Running ./csfg reboot_django will rebuild the Django Docker container.
restart¶
Running ./csfg restart is a shortcut for running:
./csfg end./csfg start
More details for each command can be found on this page.
restart_build¶
Running ./csfg restart_build is a shortcut for running:
./csfg end./csfg build./csfg start
More details for each command can be found on this page.
shell¶
Running ./csfg shell opens a bash terminal within the Django container (this requires the CS Field Guide system to be running).
This is the equivalent to entering docker-compose run django bash.
start¶
Running ./csfg start starts the development environment.
If this is the first time you’re running this script it may take roughly 15 to 30 minutes, depending on your computer and internet speed.
Once the development environment is operational, the script will perform the following tasks:
Start the Django website system
Start the Nginx server to display the website and static files
Start the database server
Once the script has performed all these tasks, the script will tell you to run the update command.
static¶
Running ./csfg static runs the commands for generating the static files for the website.
If changes are made to the static files (for example, a new image is added) when the system is running, this command needs to be entered to view the new files on the website.
static_prod¶
Running ./csfg static_prod runs the commands for generating production static files for the website.
This produces compressed SASS files without sourcemaps.
style¶
Running ./csfg style will run the flake8 and pydocstyle commands to check the style of the project.
If the output is 0 for a check, then there are zero errors.
test_backwards¶
Running ./csfg test_backwards will run the test suite in reverse.
This is useful to check if any tests are influencing the result of each other.
If this command if run on Travis CI, it will only run for a pull request.
test_coverage¶
Running ./csfg test_coverage will display a table detailing test code coverage, from the report generated by ./csfg test.
test_specific¶
Running ./csfg test_specific [MODULE_PATH] will run a specific test module.
For example, running ./csfg test_specific tests.resources.views.test_index_view will only run the tests for checking the index view of the resources application.
test_suite¶
Running ./csfg test_suite will run the test suite, and create a report detailing test code coverage.
The code coverage report can be displayed by running ./csfg test_coverage.
update¶
Running ./csfg update runs the Django makemigratations and migrate commands for updating the database schema, and then runs the custom update_data command to load the chapters content into the database.
It also runs the static command to generate static files and the make_interactive_thumbnails command which generates the thumbnails for the interactive links.
If changes are made to the chapters content when the system is running, this command needs to be run to view the new changes on the website.
update_static¶
Running ./csfg update_static updates and collects static files by running the ./csfg static and ./csfg collect_static commands.
update_data¶
Running ./csfg update_data runs the custom update_data command to load the chapters content into the database.
wipe¶
Running ./csfg wipe deletes all Docker containers and images on your computer.
Once this command has be run, a full download and rebuild of images is required to run the system (can be triggered by the build or start commands).
You now know the basic commands for using the CS Field Guide system. You are now ready to tackle the documentation for the area you wish to contribute on. Head back to the documentation homepage and choose the documentation related to the task you wish to contribute to.