diff --git a/README.rst b/README.rst index 2ed6f7a25..50745fff0 100644 --- a/README.rst +++ b/README.rst @@ -121,11 +121,14 @@ All the code and the content is freely available: Licence ======= -The application is licenced under the Affero GNU General Public License 3 or later -(AGPL 3+). +The application is licenced under the Affero GNU General Public License 3 or +later (AGPL 3+). The initial exercise and ingredient data is licensed additionally under a Creative Commons Attribution Share-Alike 3.0 (CC-BY-SA 3.0) +The documentation is released under a CC-BY-SA either version 4 of the License, +or (at your option) any later version. + Some images where taken from Wikipedia, see the SOURCES file in their respective folders for more details. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..dc20f0830 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/wgerWorkoutManager.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/wgerWorkoutManager.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/wgerWorkoutManager" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/wgerWorkoutManager" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/commands.rst b/docs/commands.rst new file mode 100644 index 000000000..5ab8200b0 --- /dev/null +++ b/docs/commands.rst @@ -0,0 +1,44 @@ +Management commands +=================== + +wger also implements a series of django commands that perform different +management functions that are sometimes needed. Call them with +``python manage.py command_name``: + +**download-exercise-images** + synchronizes the exercise images from wger.de to the local installation. Read + its help text as it could save the wrong image to the wrong exercise should + different IDs match. + +**extract-i18n** + extract strings from the database that have to be inserted manually in the PO + file when translating. These include e.g. exercise categories. + +**clear-cache** + clears different application caches. Might be needed after some updates or + just useful while testing. Please note that you must select what caches to + clear. + +**submitted-exercises** + simply prints a list of user submitted exercises + + +Cron +---- + +The following commands are built to be called regularly, via a cronjob or +similar + +**delete-temp-users** + deletes all guest users older than 1 week. At the moment this value can't be + configured + + +**email-reminders** + sends out email remainders for user that need to create a new workout. + +**inactive-members** + Sends email for gym members that have not been to the gym for a specified + amount of weeks. + + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..e76e2024a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,261 @@ +# -*- coding: utf-8 -*- +# +# wger Workout Manager documentation build configuration file, created by +# sphinx-quickstart on Mon Dec 1 22:22:02 2014. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'wger Workout Manager' +copyright = u'2015, Roland Geider' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.6' +# The full version, including alpha/beta/rc tags. +release = '1.6' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'wgerWorkoutManagerdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'wgerWorkoutManager.tex', u'wger Workout Manager Documentation', + u'Roland Geider', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'wgerworkoutmanager', u'wger Workout Manager Documentation', + [u'Roland Geider'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'wgerWorkoutManager', u'wger Workout Manager Documentation', + u'Roland Geider', 'wgerWorkoutManager', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 000000000..737e00d67 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,84 @@ +Development +=========== + +First, install all required packages:: + + $ sudo apt-get install python-virtualenv + $ sudo apt-get install python-dev + $ virtualenv python-django + $ source python-django/bin/activate + $ pip install -r requirements_devel.txt + +.. note:: + For python3 some packages have slightly different names such as ``python3-dev`` + + +Get the code and start the application. This will create a SQlite database +and populate it with data on the first run:: + + $ git clone https://github.com/rolandgeider/wger.git + $ cd wger + $ python start.py + +That's it. You can log in with the default administator user: + +* **username**: admin +* **passsword**: admin + +You can start the application again with the django server with +``python manage.py runserver``. If you pull updates and there were database changes, you can apply them with a simple ``python manage.py migrate --all``. + +Tips +---- + +Moving important files +~~~~~~~~~~~~~~~~~~~~~~ + +The start script places the settings file and the sqlite database in a non +obvious place. For developement I suggest moving them to the folder with the +code:: + + $ python start.py --show-config + Settings file: /home/user/.config/wger/settings.py + Database file: /home/user/.local/share/wger/database.sqlite + + mv /home/user/.config/wger/settings.py . + mv /home/user/.local/share/wger/database.sqlite + + +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 PEP8**: check that the code is structured as per pep8 but + with a maximum line length of 100. This can be checked automatically with the + pep8 tool (pip install pep8) from the command line (travis will do this as part + of the tests): ``pep8 --max-line-length=100--exclude="urls.py,*migrations*" wger`` + +* **code for python3**: while the application should remain compatible with + python2, use django's suggestion to mantain sanity: code for py3 and treat + py2 as a backwards compatibility requirement. If you need, you can use six. + +For other ways of contributing besides code, you might want to take a look at the contribute page. diff --git a/docs/gym.rst b/docs/gym.rst new file mode 100644 index 000000000..c7465a049 --- /dev/null +++ b/docs/gym.rst @@ -0,0 +1,38 @@ +Gym admnistration +================= + +wger has basic support for gym management. There are 3 groups used for the +different administrative roles: + +* **general manager:** Can manage (add, edit, delete) the different gyms for the + installation but is not allowed to access or add members. +* **gym manager:** Can manage users for a single gym. +* **trainer:** Can manage the workouts and other data for the members of a + single gym. + +If the installation is used for a single gym only, you can set the default gym. +This will update all existing users as well as newly registered ones so they +belong to that gym + + +Configuration +------------- + +Inactive members +~~~~~~~~~~~~~~~~ +The idea behind the inactive members is that trainers want to know which users +have not visited the gym for longer than X weeks and e.g. contact them. +'Inactive' means here that they don't have any logs in the time period. + +This can be configured in the following ways: + +**number of weeks** + The value in weeks after which users are considered inactive (default is 8). + This applies to the whole gym and can be deactivated by entering a 0. + +**trainer configuration** + Each trainer can opt-out of receiving such emails + +**user configuration** + Individual users can be opt-out of being included in the reminder emails if + they don't want to use the log or any other reason. diff --git a/docs/i18n.rst b/docs/i18n.rst new file mode 100644 index 000000000..24e3a21ff --- /dev/null +++ b/docs/i18n.rst @@ -0,0 +1,42 @@ +Internationalization (i18n) +=========================== + + + +Updating the translation files +------------------------------ + +wger uses django's translation infrastructure, but there are a couple of things +that need to be considered. First, update your po files with the default django command (run this in the wger folder):: + + django-admin makemessages --locale en + +Extract some translatable strings from the database such as exercise categories +and muscle names:: + + python manage.py extract-i18n + +and add them to the end of ``locale/en/LC_MESSAGES/django.po``. Once you have +translated the file, compile it with:: + + django-admin compilemessages --all + + +Adding new languages +-------------------- + +Besides adding the new translations to the locale folder, they have to be +activated in django and in the application itself. + +* **django:** Add an entry to ``LANGUAGES`` in ``settings_global.py`` +* **wger:** Add the new language in the language admin page and set the + visibility of excercises and ingredients +* **fixtures:** After having added the language in the admin module, export + the database, filter it with the ``filter-fixtures.py`` script in + ``extras/scripts`` and copy ``language_config.json`` to the fixtures folder + in the config app and ``languages.json`` to core. +* **flag icon:** Add an appropriate flag icon in SVG format in ``images/icons/flag-NAME.svg`` + in the static folder of the core application + +.. note:: + At the moment composed language codes such as pt-BR are **not** supported. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..fa9410792 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,85 @@ +.. wger Workout Manager documentation master file, created by + sphinx-quickstart on Mon Dec 1 22:22:02 2014. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to wger Workout Manager's documentation! +================================================ + +wger is a free, open source web application that manages your exercises and +personal workouts, weight and diet plans. It can also be used as a simple gym +management utility, providing different administrative roles (trainer, manager, +etc.). It offers a REST API as well, for easy integration with other projects +and tools. It is written with python/django and uses jQuery and some D3js for charts. + +For more details and a live system, refer to the project's site: +https://github.com/rolandgeider/wger + + +This documentation is intended for developers and administrators of the software. + + +Installation and development +---------------------------- + +* :doc:`install` + + * :doc:`commands` + * :doc:`i18n` + * :doc:`settings` + +* :doc:`development` + + +Administration guide +-------------------- +* :doc:`gym` + +.. toctree:: + :maxdepth: 2 + + +Contact +------- + +Feel free to contact us if you found this useful or if there was something that +didn't behave as you expected (in this case you can also open a ticket on the +issue tracker). + +* **twitter:** https://twitter.com/wger_de +* **mailing list:** https://groups.google.com/group/wger / wger@googlegroups.com, + no registration needed +* **IRC:** channel #wger on freenode.net, webchat: http://webchat.freenode.net/?channels=wger +* **issue tracker:** https://github.com/rolandgeider/wger/issues + + +Sources +------- + +All the code and the content is freely available and is hosted on github: +https://github.com/rolandgeider/wger + + +Licence +------- + +The application is licenced under the Affero GNU General Public License 3 or +later (AGPL 3+). + +The initial exercise and ingredient data is licensed additionally under a +Creative Commons Attribution Share-Alike 3.0 (CC-BY-SA 3.0) + +The documentation is released under a CC-BY-SA either version 4 of the License, +or (at your option) any later version. + +Some images where taken from Wikipedia, see the SOURCES file in their respective +folders for more details. + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` +.. * :ref:`modindex` + diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 000000000..5632646af --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,141 @@ +Installation +============ + +This file gives a broad description of the necessary steps to install wger on a +production environment with apache as a webserver. Since this is a regular +django application, refer to its documentation if your setup differs. For a +developemt setup refer to :doc:`development` + +The application is compatible and regularly tested with + +* sqlite, postgres +* python 2.7, 3.3 and 3.4 + + + +Databasse +--------- + +postgreSQL +~~~~~~~~~~ + +Install the postgres server and create a database and a user:: + + createdb wger + psql wger + CREATE USER wger; + GRANT ALL PRIVILEGES ON DATABASE wger to wger; + + +sqlite +~~~~~~ + +No further steps necessary. + + +Apache +------ + +Install apache and the WSGI module:: + + sudo apt-get install apache2 libapache2-mod-wsgi + sudo vim /etc/apache2/apache2.conf + + +Configure apache to serve the application:: + + >>> + WSGIScriptAlias / /home/myuser/wger/wger/wsgi.py + WSGIPythonPath /home/myuser/wger:/home/myuser/venv-wger/lib/python2.7/site-packages + + + + Require all granted + + + + + + Alias /static/ /home/myuser/static/ + + Require all granted + + + Alias /media/ /home/myuser/media/ + + Require all granted + + ... # Log files, etc. + + + + +Application +----------- + +Install the necessary packages to create a virtualenv for python (note that you +might need to install more if you want the thumbnailer to be able to support +more image formats, consult the documentation for pillow for more details):: + + sudo apt-get install git python-dev python-virtualenv + virtualenv venv-wger + source venv-wger/bin/activate + +If using sqlite, create a folder for it (must be writable by the apache user +so you can just give it the folder with chown):: + + mkdir db + chmod o+w db + + touch db/database.sqlite + chmod o+w database.sqlite + + + +Create folders to collect all static resources and save uploaded files (must +be readable by the apache process):: + + mkdir static + + mkdir media + chmod o+w media + +Get the application:: + + git clone https://github.com/rolandgeider/wger.git + cd wger + pip install -r requirements.txt + python extras/scripts/create_local_settings.py + +Edit your ``settings.py`` file and set the database, ``SITE_URL``, +``STATIC_ROOT`` and ``MEDIA_ROOT``:: + + + 'default': { + 'ENGINE': 'django.db.backends.sqlite3', + 'NAME': u'/home/myuser/db/database.sqlite', + 'USER': '', + 'PASSWORD': '', + 'HOST': '', + 'PORT': '', + } + } + + >>> SITE_URL anpassen + >>> STATIC_ROOT = '/home/myuser/static' + >>> MEDIA_ROOT = '/home/myuser/wger/media' + +Run the installation scritpt, this will load all initial data (exit after it +is done and tries to start a web browser):: + python start.py + + +Start.py will create a default administator user (you probably want to change +the password as soon as you log in): + +* **username**: admin +* **password**: admin + +Collect all static resources:: + + python manage.py collectstatic diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 000000000..ac9415dc1 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,242 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\wgerWorkoutManager.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\wgerWorkoutManager.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/docs/settings.rst b/docs/settings.rst new file mode 100644 index 000000000..2a038a713 --- /dev/null +++ b/docs/settings.rst @@ -0,0 +1,15 @@ +Settings +======== + +You can configure some of the application behaviour with the ``WGER_SETTINGS`` +dictionary in your settings file. Currently the following options are supported: + +* **USE_RECAPTCHA**: Default ``False``. Controls whether a captcha challenge + will be presented when new users register. + + +.. note:: + If you want to override a default setting, don't overwrite all the dictionary + but only the keys you need, e.g. ``WGER_SETTINGS['foo'] = 'bar'``. This avoids + problems when new keys are added in the global settings. + diff --git a/wger/software/templates/code.html b/wger/software/templates/code.html index 9024273fa..6a09c39d9 100644 --- a/wger/software/templates/code.html +++ b/wger/software/templates/code.html @@ -60,265 +60,19 @@ file and a SQLite database with a standard superuser:{% endblocktrans %}

{% blocktrans %}You can later simply call wger again to start the application.{% endblocktrans %}

-

{% trans "Notes" %}

- -
    -
  • {% blocktrans %}Use wger --help to see available options{% endblocktrans %}
    • -
  • {% blocktrans %}You should edit the settings.py and enter your -reCaptcha keys. You can leave -this blank or enter bogus data, but you won't be able e.g. to register new users.{% endblocktrans %}
    • -
  • {% blocktrans %}For the sitemap.xml file to be correctly generated, -you need to set a correct domain name in the sites app (only needed for search -engines). This is done via django's admin interface (/admin/){% endblocktrans %}
    • -
  • {% blocktrans %}This is a Django application, so refer for details to its -documentation page -if things don't go as expected.{% endblocktrans %}
    • - -
+

{% blocktrans %}Use wger --help to see available options{% endblocktrans %}

-

Developer guide

- - - -

How to get the code

-

The code is hosted both on github and on bitbucket. If -you are unfamiliar with mercurial or git, take a look at HG -init or Pro Git. Both repositories -are mantained in sync, so you should be able to work on either one (issues -and pull requests are only collected in github).

- -
-
- - github (GIT) -
- the main repository - -
-
- git clone https://github.com/rolandgeider/wger.git -
-
- - -
-
- - bitbucket (HG) -
- a mirror of the main repo - -
-
- hg clone https://bitbucket.org/rolandgeider/wger -
-
- - - -

The file structure you get once you clone the repo should be self explaining:

- -
    -
  • - wger: the django project and its applications -
    • -
  • - extras: additional helper scrips, e.g. a benchmarking - script with funkload, a tool to create a local settings.py file, etc. -
    • -
- - - -

How to get started

-

The installation procedure is very similar to the one -described above for the packaged version. The notes and infos there also apply, -so read that section too. First, install all packages (note that you might need -to install more packages if you want the thumbnailer to be able to read more -image formats, consult the documentation for pillow -for more details):

- -
-$ sudo apt-get install python-virtualenv
-$ sudo apt-get install python-dev
-$ virtualenv python-django
-$ source python-django/bin/activate
-$ pip install -r requirements.txt
-
- -

Get the code, create a superuser and start the webserver:

- -
-$ git clone https://github.com/rolandgeider/wger.git
-$ cd wger
-$ python start.py
-
- -

That's it. You can either start the server again with -start.py or do it the django way with -python manage.py runserver.

- - -

If you pull updates and there were database changes, you -can apply them with a simple python manage.py migrate --all.

- -

Management commands

-

wger also implements a series of django commands that perform different -management functions that are sometimes needed:

- -

- python manage.py ... -

- -
    -
  • - download-exercise-images - synchronizes the exercise - images from wger.de to the local installation. Read its help text - as it could save the wrong image to the wrong exercise should different - IDs match. -
    • -
  • - extract-i18n - extract strings from the database - that have to be inserted manually in the PO file when translating. These - include e.g. exercise categories. -
    • -
  • - clear-cache - clears different application caches. Might be - needed after some updates or just useful while testing. Please note that - you must select what caches to clear. -
    • -
  • - delete-temp-users - deletes all guest users older than 1 week. - You will probably want to run this regularly via a cron job. -
    • -
  • - email-remainders - sends out email remainders for user that - need to create a new workout. Usually run via cron job. -
    • -
  • - submitted-exercises - prints a list of user submitted - exercises -
    • -
- -

Settings files

-

wger uses two settings files to configure django:

- -
    -
  • - settings.py: the settings for the local installation. - You can overwrite global settings here, the output of python start.py - --show-config will show you the default location. -
    • -
  • - settings_global.py: global settings, usually this file - is never edited. -
    • -
- - - - - -

How to contribute code

-

For other ways of contributing besides code, you might -want to take a look at the contribute page

- -
    -
  • - 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 you can rebase 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 PEP8: check that - the code is structured as per pep8 but with a maximum line length of 100. - This can be checked automatically with the pep8 tool (pip install pep8) - from the command line (travis will do this as part of the tests): - pep8 --max-line-length=100--exclude="urls.py,*migrations*" wger -
    • -
- - - - -

Custom hosting

-

If you want to host this with some other environment (apache, -postgreSQL, etc.), you need to perform some steps manually. First, install -the necessary packages and dependencies as described before.

- -

wger is regularly tested with the following software versions:

-
    -
  • Django: 1.6
    • -
  • Databases: sqlite, mysql, postgres
    • -
  • Python: 2.7, 3.3, 3.4
    • -
- -

Setup any database -that Django -supports. Then create a settings file and edit it as needed. There is -another configuration file, settings_global.py that contains other global -settings.

- - -$ python extras/scripts/create_local_settings.py - - -

Initialise the database, create a super user and load these -fixtures:

- -
-$ python manage.py syncdb
-$ python manage.py migrate core
-$ python manage.py migrate --all
-$ python manage.py loaddata licenses
-$ python manage.py loaddata languages
-$ python manage.py loaddata language_config
-$ python manage.py loaddata days_of_week
-$ python manage.py loaddata equipment
-$ python manage.py loaddata muscles
-$ python manage.py loaddata categories
-$ python manage.py loaddata exercises
-$ python manage.py loaddata ingredients
-$ python manage.py loaddata weight_units
-$ python manage.py loaddata ingredient_units
-
- -

What you do next depends on the server you use and how you -want to serve the application (mod_wsgi, fastCGI). There is a sample wsgi.py -file in the wger folder, edit it and adapt it to your needs and make the server -serve it, e.g. per mod_wsgi. Consult in any case the -django -documentation on the topic.

+

Further documentation

+

There is a more extensive installation and developer documentation available +in the docs folder of the project. To compile it simply do a +make html and open index.html in _build.

{% endblock %} {% block sidebar %} -

{% trans "Overview" %}

- - {% endblock %}