Self hosted FLOSS fitness/workout, nutrition and weight tracker
Improvements to the documentation
Roland Geider513edbe0fa17
diff --git a/README.rst b/README.rstindex 5223a10d5..19eab667a 100644--- a/README.rst+++ b/README.rst@@ -87,10 +87,10 @@ Then install the python packages from pypi in the virtualenv::$ pip install -r requirements.txt # or requirements_devel.txt to develop$ python setup.py develop$ wger create_settings \- --settings-path /home/wger/wger/settings.py \- --database-path /home/wger/wger/database.sqlite+ --settings-path /path/to/current/folder/settings.py \+ --database-path /path/to/current/folder/database.sqlite$ wger bootstrap \- --settings-path /home/wger/wger/settings.py \+ --settings-path /path/to/current/folder/settings.py \--no-start-server$ python manage.py runserver@@ -116,16 +116,13 @@ Stable version (from PyPI)2) Start the application. This will download the required JS and CSS librariesand create a SQlite database and populate it with data on the first run.-+ Then, log in as: **admin**, password **admin**::$ wger bootstrap-3) Log in as: **admin**, password **admin**---4) To start the installation again, just call wger start::+3) To start the installation again, just call wger start::$ wger startdiff --git a/docs/codingstyle.rst b/docs/codingstyle.rstindex d0cfa5c48..6372805f6 100644--- a/docs/codingstyle.rst+++ b/docs/codingstyle.rst@@ -29,8 +29,8 @@ Javascript* Functions called from Django templates need to start with ``wger``-Check Coding Style-==================+Automatic coding style checks+-----------------------------The coding style is automatically check by Travis-CI. To manually check yourfiles you can run the following commands:diff --git a/docs/development.rst b/docs/development.rstindex 2a06e56b7..00b00c1e4 100644--- a/docs/development.rst+++ b/docs/development.rst@@ -67,147 +67,3 @@ That's it. You can log in with the default administator user:You can start the application again with the django server with``python manage.py runserver``.--.. _tips:--Tips-------Updating the code-~~~~~~~~~~~~~~~~~--When pulling updates from upstream there are a couple of things to consider.-These steps apply to all installation methods above.--Upgrading the database-``````````````````````--There are regularly changes and upgrades to the database schema (these may also-come from new versions of django or the installed dependencies). If you start-the development server and see a message that there are unapplied migrations,-just do ``python manage.py migrate --all``.--Downloading dependencies with Bower-```````````````````````````````````--Bower is used to download different JS and CSS libraries. If you update master-it is recommended that you first delete the existing libraries-(``rm wger/core/static/bower_components``) and then download the new versions-with::-- $ python manage.py bower install---Some info about bower, during the bootstrap process bower is installed locally-to src/wger. If this didn't work and you get an error saying that bower is not-installed, you can manually install it by going to the project's root directory-and performing the step manually::-- $ cd src/wger- $ npm install bower--Alternatively, you can manually set the path to the bower binary by editing-``BOWER_PATH`` (see ``wger/settings_global.py``).---Clearing the cache-``````````````````--Sometimes there are changes to the internal changes of the cached structures.-It is recommended that you just clear all the existing caches-``python manage.py clear-cache --clear-all``--Miscellaneous settings-~~~~~~~~~~~~~~~~~~~~~~--The following settings can be very useful during development (add to your-settings.py):---**Setting the email backend**- Use the console backend, all sent emails will be printed to it::-- EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'--Dummy data generator-~~~~~~~~~~~~~~~~~~~~--To properly test the different parts of the application for usability or-performance, it is often very useful to have some data to work with. For this-reason, there is a dummy data generator script in-extras/dummy_generator/generator.py. It allows you to generate entries for-users, gyms, workouts and logs. For detailed usage options do::-- python generator.py --help--Or for options for, e.g. user generation::-- python generator.py users --help--To get you started, you might want to invoke the script in the following way. This-will create 10 gyms and 300 users, randomly assigning them to a different gym. Each-user will have 20 workouts and each exercise in each workout 30 log entries::-- python generator.py gyms 10- python generator.py users 300- python generator.py workouts 20- python generator.py logs 30- python generator.py sessions random- python generator.py weight 100- python generator.py nutrition 20--.. note::- All generated users have their username as password.--.. note::- While it is possible to generate hundreds of users, gyms are more restricted and- you will probably get duplicate names if you generate more than a dozen.---Selectively running tests-~~~~~~~~~~~~~~~~~~~~~~~~~--If you do a ``python manage.py test`` you will run the complete testsuite, and-this can take a while. You can control which tests will be executed like this.--Test only the tests in the 'core' app::-- python manage.py test wger.core--Test only the tests in the 'test_user.py` file in the core app::-- python manage.py test wger.core.tests.test_user--Test only the tests in 'StatusUserTestCase' in the file 'test_user.py` file in-the core app::-- python manage.py test wger.core.tests.test_user.StatusUserTestCase---Using runserver_plus-~~~~~~~~~~~~~~~~~~~~--During development you can use ``runserver_plus`` instead of the default django-server as you can use an interactive debugger directly from the browser if an-exception occurs. It also accepts the same command line options. For this just-install the following packages::-- pip install django_extensions werkzeug- python manage.py runserver_plus [options]---Contributing---------------* **Send pull requests**: for new code you want to share, please send pull- requests in github. Sending patches by email or attaching them to an issue- means a lot more of work. It's recommended that you work on a feature branch- when working on something, specially when it's something bigger. While many- people insist on rebasing before sending a pull request, it's not necessary.--* **Run the tests**: wger is proud to have a test coverage of over 90%. When you- implement something new, don't forget to run the testsuite and write approriate- tests for the new code. If you use github, configure the awesome Travis CI,- there is already a .travis file in the sources.--* **Code according to the coding style**: :ref:`codingstyle`diff --git a/docs/docker.rst b/docs/docker.rstindex 4d41e94b4..c3ddb135d 100644--- a/docs/docker.rst+++ b/docs/docker.rst@@ -1,5 +1,5 @@-Docker-======+Docker images+=============There are docker files available to quickly get a version of wger up andrunning. They are all located under ``extras/docker`` if you want to build@@ -56,4 +56,4 @@ Run a container and start the application::docker run -ti --name wger.apache --publish 8000:80 wger/apacheNow you can access the application on port 8000 of your host (probably just-http://localhost:8000).\ No newline at end of file+http://localhost:8000).diff --git a/docs/install.rst b/docs/getting_started.rstsimilarity index 64%rename from docs/install.rstrename to docs/getting_started.rstindex 32f29ffa4..e859c753d 100644--- a/docs/install.rst+++ b/docs/getting_started.rst@@ -1,13 +1,15 @@-.. _install:+.. _getting_started:-Installation-============+Getting started+===============-This file gives a broad description of the necessary steps to install wger-on a debian based linux distribution. If your setup differs (e.g. in Red Hat-based distros the package names are slightly different) you will need to-change the steps but in the end, this is a regular django application so it-should run wherever django runs.+You can get a local instance of wger installed in a couple of minutes.++It is recommended to install a development instance or start a docker+image if you just want to try the application on your server or PC. All+the following steps are performed on a debian based linux distribution.+If your setup differs (e.g. in Red Hat based distros the package names are+slightly different) you will need to change the steps as appropriate.The application is compatible and regularly tested with@@ -24,10 +26,6 @@ contact page.in the development page apply to all the installation options.--Base------These are the necessary packages for both development and production(node and npm are only used to download JS and CSS libraries)::@@ -48,20 +46,10 @@ On fedora 23::the appropriate packages (e.g. python-dev instead of python3-dev, etc.)!-Development--------------For development consult the :doc:`development` section.---Production-------------For a more production-like setting with apache and mod-wsgi consult the-:doc:`production` chapter.-+.. toctree::+ :maxdepth: 2-Docker-------+ development+ docker+ production-There are also docker images available, see the :doc:`docker` chapter.diff --git a/docs/index.rst b/docs/index.rstindex 18713a8a3..5b84c28bd 100644--- a/docs/index.rst+++ b/docs/index.rst@@ -24,18 +24,19 @@ Installation and development.. toctree:::maxdepth: 2- install+ getting_started+ settingscommands+ tips_and_tricks+ codingstylei18n-Administration guide--------------------.. toctree:::maxdepth: 2- settingsgymdiff --git a/docs/tips_and_tricks.rst b/docs/tips_and_tricks.rstnew file mode 100644index 000000000..5a5aa3a02--- /dev/null+++ b/docs/tips_and_tricks.rst@@ -0,0 +1,143 @@+.. _tips:++Tips and tricks+---------------++Updating the code+~~~~~~~~~~~~~~~~~++When pulling updates from upstream there are a couple of things to consider.+These steps apply to all installation methods above.++Upgrading the database+``````````````````````++There are regularly changes and upgrades to the database schema (these may also+come from new versions of django or the installed dependencies). If you start+the development server and see a message that there are unapplied migrations,+just do ``python manage.py migrate --all``.++Downloading dependencies with Bower+```````````````````````````````````++Bower is used to download different JS and CSS libraries. If you update master+it is recommended that you first delete the existing libraries+(``rm wger/core/static/bower_components``) and then download the new versions+with::++ $ python manage.py bower install+++Some info about bower, during the bootstrap process bower is installed locally+to src/wger. If this didn't work and you get an error saying that bower is not+installed, you can manually install it by going to the project's root directory+and performing the step manually::++ $ cd src/wger+ $ npm install bower++Alternatively, you can manually set the path to the bower binary by editing+``BOWER_PATH`` (see ``wger/settings_global.py``).+++Clearing the cache+``````````````````++Sometimes there are changes to the internal changes of the cached structures.+It is recommended that you just clear all the existing caches+``python manage.py clear-cache --clear-all``++Miscellaneous settings+~~~~~~~~~~~~~~~~~~~~~~++The following settings can be very useful during development (add to your+settings.py):+++**Setting the email backend**+ Use the console backend, all sent emails will be printed to it::++ EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'++Dummy data generator+~~~~~~~~~~~~~~~~~~~~++To properly test the different parts of the application for usability or+performance, it is often very useful to have some data to work with. For this+reason, there is a dummy data generator script in+extras/dummy_generator/generator.py. It allows you to generate entries for+users, gyms, workouts and logs. For detailed usage options do::++ python generator.py --help++Or for options for, e.g. user generation::++ python generator.py users --help++To get you started, you might want to invoke the script in the following way. This+will create 10 gyms and 300 users, randomly assigning them to a different gym. Each+user will have 20 workouts and each exercise in each workout 30 log entries::++ python generator.py gyms 10+ python generator.py users 300+ python generator.py workouts 20+ python generator.py logs 30+ python generator.py sessions random+ python generator.py weight 100+ python generator.py nutrition 20++.. note::+ All generated users have their username as password.++.. note::+ While it is possible to generate hundreds of users, gyms are more restricted and+ you will probably get duplicate names if you generate more than a dozen.+++Selectively running tests+~~~~~~~~~~~~~~~~~~~~~~~~~++If you do a ``python manage.py test`` you will run the complete testsuite, and+this can take a while. You can control which tests will be executed like this.++Test only the tests in the 'core' app::++ python manage.py test wger.core++Test only the tests in the 'test_user.py` file in the core app::++ python manage.py test wger.core.tests.test_user++Test only the tests in 'StatusUserTestCase' in the file 'test_user.py` file in+the core app::++ python manage.py test wger.core.tests.test_user.StatusUserTestCase+++Using runserver_plus+~~~~~~~~~~~~~~~~~~~~++During development you can use ``runserver_plus`` instead of the default django+server as you can use an interactive debugger directly from the browser if an+exception occurs. It also accepts the same command line options. For this just+install the following packages::++ pip install django_extensions werkzeug+ python manage.py runserver_plus [options]+++Contributing+------------++* **Send pull requests**: for new code you want to share, please send pull+ requests in github. Sending patches by email or attaching them to an issue+ means a lot more of work. It's recommended that you work on a feature branch+ when working on something, specially when it's something bigger. While many+ people insist on rebasing before sending a pull request, it's not necessary.++* **Run the tests**: wger is proud to have a test coverage of over 90%. When you+ implement something new, don't forget to run the testsuite and write approriate+ tests for the new code. If you use github, configure the awesome Travis CI,+ there is already a .travis file in the sources.++* **Code according to the coding style**: :ref:`codingstyle`