help-tokens

########### help-tokens ###########

Django app for linking to help pages with short tokens.

|pypi-badge| |ci-badge| |codecov-badge| |pyversions-badge| |license-badge|

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 <https://github.com/openedx/.github/blob/master/CONTRIBUTING.md>_ 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 <https://github.com/openedx/help-tokens/blob/master/.github/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 <https://github.com/openedx/help-tokens/blob/master/.github/ISSUE_TEMPLATE.md>_

Reporting Security Issues

---

Please do not report security issues in public. Please email [e-mail].

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: https://open.edx.org/getting-help

.. |pypi-badge| image:: https://img.shields.io/pypi/v/help-tokens.svg :target: https://pypi.python.org/pypi/help-tokens/ :alt: PyPI

.. |ci-badge| image:: https://github.com/openedx/help-tokens/workflows/Python%20CI/badge.svg?branch=master :target: https://github.com/openedx/help-tokens/actions?query=workflow%3A%22Python+CI%22 :alt: CI

.. |codecov-badge| image:: http://codecov.io/github/edx/help-tokens/coverage.svg?branch=master :target: http://codecov.io/github/edx/help-tokens?branch=master :alt: Codecov

.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/help-tokens.svg :target: https://pypi.python.org/pypi/help-tokens/ :alt: Supported Python versions

.. |license-badge| image:: https://img.shields.io/github/license/edx/help-tokens.svg :target: https://github.com/openedx/help-tokens/blob/master/LICENSE.txt :alt: License

Change Log

---

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

This project adheres to Semantic Versioning (http://semver.org/).

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

[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.