GitLocker: The Coding Marketplace

Description:

helptokens 2.4.0

Django app for linking to help pages with short tokens.

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

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.

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

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:
HELP_TOKENS_BOOKS = {
'learner': 'http://edx.readthedocs.io/projects/learner-guide',
'course_author': 'http://edx.readthedocs.io/projects/running-a-course',
}

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:
[pages]
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:
[locales]
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.

License
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.
PR description template should be automatically applied if you are sending PR from GitHub interface; otherwise you
can find it it at PULL_REQUEST_TEMPLATE.md
Issue report template should be automatically applied if you are sending it from GitHub UI as well; otherwise you
can find it at ISSUE_TEMPLATE.md

Reporting Security Issues
Please do not report security issues in public. Please email security@openedx.org.

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.

Change Log

[2.4.0] - 2024-03-29

Added support for Python 3.11
Dropped support for Django 3.2, Django 4.0 and Django 4.1

[2.3.0] - 2023-08-02

Added support for Django 4.2

[2.2.0] - 2022-01-20

Dropped support for django2.2, 3.0, 3.1 and 3.2
Added Django40 support in CI

[2.1.0] - 2020-07-07

Added support for django3.0, 3.1 and 3.2

[2.0.0] - 2020-01-19

Removed support of python3.5

[1.1.0] - 2020-05-05

Removed support of Django < 2.2 version
Added support for python 3.8

[1.0.3] - 2017-07-17

Updated tests to support Django 1.11
Updated dependency versions

[1.0.2] - 2017-05-16

Fixed the README.

[1.0.1] - 2017-05-15

First version on PyPI.

[1.0.0] - 2017-05-03

First release.