Skip to main content

Django app for linking to help pages with short tokens

Project description


Django app for linking to help pages with short tokens.

|pypi-badge| |travis-badge| |codecov-badge| |pyversions-badge|


There are various factors that affect what help page an application should link

- There may be a number of relevant books

- The version of the application might affect which book to display

- The application's language might affect which book to display

This small Django app provides a means to use "help tokens" on the application
pages, and then use those tokens, and various other settings, to determine the
actual URL to use.


Help-tokens provides a context processor, and a redirection URL. Configuration
is in a number of settings.


Help-tokens reads these Django settings to create URLs:

* HELP_TOKENS_INI_FILE: Path to a .ini file containing help token definitions.
The format of the ini file is described below.

* HELP_TOKENS_BOOKS: a dictionary mapping book slugs to URLs. For example::

'learner': '',
'course_author': '',

* HELP_TOKENS_VERSION: a string used as part of the final URL, to choose the
correct version of the book. For example, `"latest"`.

* HELP_TOKENS_LANGUAGE_CODE: the language code to use as part of the book URL,
mapped through the [locales] section of the ini file.

INI file format

The .ini file pointed to by HELP_TOKENS_INI_FILE contains the definitions of
the help tokens themselves.

The `[pages]` section defines the help tokens. Each help token definition
consists of a book slug (defined in HELP_TOKENS_BOOKS), a colon, and a URL
path. The `default` token is used for missing tokens. For example::

default = learner:index.html
instructor = learner:SFD_instructor_dash_help.html
course = learner:index.html

cohortmanual = course_author:course_features/cohorts/cohort_config.html#assign-learners-to-cohorts-manually
cohortautomatic = course_author:course_features/cohorts/cohorts_overview.html#all-automated-assignment

The `[locales]` section defines language codes, used with
HELP_TOKENS_LANGUAGE_CODE to determine the language portion of the URL::

default = en
en = en
en_us = en

Context processor

The context processor is `"help_tokens.context_processor"`. It adds a function
`get_online_help_info`. Call it with a help token, and it will return a dict
with a `doc_url` entry, the help URL. You can use it like this in a template::

<a href="${get_online_help_info('visibility')['doc_url']}">...</a>

This interface is a bit verbose, but is to maintain backward compatibility with
a previous implementation of this context processor.

Redirection view

The `help_tokens.urls` URLs define a view that redirects to a help URL. You can
include it in your app::

# For redirecting to help pages.
url(r'^help_token/', include('help_tokens.urls')),

Then visiting `help_token/foobar` will redirect to the URL defined by the
"foobar" help token.


The code in this repository is licensed under the AGPL 3.0 unless otherwise
noted. Please see ``LICENSE.txt`` for details.

How To Contribute

Contributions are very welcome.

Please read `How To Contribute <>`_ for details.

Even though they were written with ``edx-platform`` in mind, the guidelines
should be followed for Open edX code in general.

PR description template should be automatically applied if you are sending PR from GitHub interface; otherwise you
can find it it at ` <>`_

Issue report template should be automatically applied if you are sending it from GitHub UI as well; otherwise you
can find it at ` <>`_

Reporting Security Issues

Please do not report security issues in public. Please email

Getting Help

Have a question about this repository, or about Open edX in general? Please
refer to this `list of resources`_ if you need any assistance.

.. _list of resources:

.. |pypi-badge| image::
:alt: PyPI

.. |travis-badge| image::
:alt: Travis

.. |codecov-badge| image::
:alt: Codecov

.. |pyversions-badge| image::
:alt: Supported Python versions

.. |license-badge| image::
:alt: License

Change Log

All enhancements and patches to help_tokens will be documented
in this file. It adheres to the structure of ,
but in reStructuredText instead of Markdown (for ease of incorporation into
Sphinx documentation and the PyPI description).

This project adheres to Semantic Versioning (

.. There should always be an "Unreleased" section for changes pending release.

[1.0.1] - 2017-05-15

* First version on PyPI.

[1.0.0] - 2017-05-03


* First release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

help-tokens-1.0.1.tar.gz (20.8 kB view hashes)

Uploaded source

Built Distribution

help_tokens-1.0.1-py2.py3-none-any.whl (10.2 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page