###########
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 security@edx.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.
.. _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.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.
Raw data
{
"_id": null,
"home_page": "https://github.com/openedx/help-tokens",
"name": "help-tokens",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Django edx",
"author": "edX",
"author_email": "oscm@edx.org",
"download_url": "https://files.pythonhosted.org/packages/77/36/76c0923ca0f9e26ec4b93553695e56bd26eeb348fc8c4b01f763194f9ab6/help-tokens-2.3.0.tar.gz",
"platform": null,
"description": "###########\nhelp-tokens\n###########\n\nDjango app for linking to help pages with short tokens.\n\n|pypi-badge| |ci-badge| |codecov-badge| |pyversions-badge|\n|license-badge|\n\n\nOverview\n********\n\nThere are various factors that affect what help page an application should link\nto:\n\n- There may be a number of relevant books\n\n- The version of the application might affect which book to display\n\n- The application's language might affect which book to display\n\nThis small Django app provides a means to use \"help tokens\" on the application\npages, and then use those tokens, and various other settings, to determine the\nactual URL to use.\n\n\nDocumentation\n*************\n\nHelp-tokens provides a context processor, and a redirection URL. Configuration\nis in a number of settings.\n\nSettings\n========\n\nHelp-tokens reads these Django settings to create URLs:\n\n* HELP_TOKENS_INI_FILE: Path to a .ini file containing help token definitions.\n The format of the ini file is described below.\n\n* HELP_TOKENS_BOOKS: a dictionary mapping book slugs to URLs. For example::\n\n HELP_TOKENS_BOOKS = {\n 'learner': 'http://edx.readthedocs.io/projects/learner-guide',\n 'course_author': 'http://edx.readthedocs.io/projects/running-a-course',\n }\n\n* HELP_TOKENS_VERSION: a string used as part of the final URL, to choose the\n correct version of the book. For example, `\"latest\"`.\n\n* HELP_TOKENS_LANGUAGE_CODE: the language code to use as part of the book URL,\n mapped through the [locales] section of the ini file.\n\nINI file format\n===============\n\nThe .ini file pointed to by HELP_TOKENS_INI_FILE contains the definitions of\nthe help tokens themselves.\n\nThe `[pages]` section defines the help tokens. Each help token definition\nconsists of a book slug (defined in HELP_TOKENS_BOOKS), a colon, and a URL\npath. The `default` token is used for missing tokens. For example::\n\n [pages]\n default = learner:index.html\n instructor = learner:SFD_instructor_dash_help.html\n course = learner:index.html\n\n cohortmanual = course_author:course_features/cohorts/cohort_config.html#assign-learners-to-cohorts-manually\n cohortautomatic = course_author:course_features/cohorts/cohorts_overview.html#all-automated-assignment\n\nThe `[locales]` section defines language codes, used with\nHELP_TOKENS_LANGUAGE_CODE to determine the language portion of the URL::\n\n [locales]\n default = en\n en = en\n en_us = en\n\n\nContext processor\n=================\n\nThe context processor is `\"help_tokens.context_processor\"`. It adds a function\n`get_online_help_info`. Call it with a help token, and it will return a dict\nwith a `doc_url` entry, the help URL. You can use it like this in a template::\n\n <a href=\"${get_online_help_info('visibility')['doc_url']}\">...</a>\n\nThis interface is a bit verbose, but is to maintain backward compatibility with\na previous implementation of this context processor.\n\n\nRedirection view\n================\n\nThe `help_tokens.urls` URLs define a view that redirects to a help URL. You can\ninclude it in your app::\n\n # For redirecting to help pages.\n url(r'^help_token/', include('help_tokens.urls')),\n\nThen visiting `help_token/foobar` will redirect to the URL defined by the\n\"foobar\" help token.\n\n\nLicense\n*******\n\nThe code in this repository is licensed under the AGPL 3.0 unless otherwise\nnoted. Please see ``LICENSE.txt`` for details.\n\nHow To Contribute\n*****************\n\nContributions are very welcome.\n\nPlease read `How To Contribute <https://github.com/openedx/.github/blob/master/CONTRIBUTING.md>`_ for details.\n\n\nPR description template should be automatically applied if you are sending PR from GitHub interface; otherwise you\ncan find it it at `PULL_REQUEST_TEMPLATE.md <https://github.com/openedx/help-tokens/blob/master/.github/PULL_REQUEST_TEMPLATE.md>`_\n\nIssue report template should be automatically applied if you are sending it from GitHub UI as well; otherwise you\ncan find it at `ISSUE_TEMPLATE.md <https://github.com/openedx/help-tokens/blob/master/.github/ISSUE_TEMPLATE.md>`_\n\nReporting Security Issues\n*************************\n\nPlease do not report security issues in public. Please email security@edx.org.\n\nGetting Help\n************\n\nHave a question about this repository, or about Open edX in general? Please\nrefer to this `list of resources`_ if you need any assistance.\n\n.. _list of resources: https://open.edx.org/getting-help\n\n\n.. |pypi-badge| image:: https://img.shields.io/pypi/v/help-tokens.svg\n :target: https://pypi.python.org/pypi/help-tokens/\n :alt: PyPI\n\n.. |ci-badge| image:: https://github.com/openedx/help-tokens/workflows/Python%20CI/badge.svg?branch=master\n :target: https://github.com/openedx/help-tokens/actions?query=workflow%3A%22Python+CI%22\n :alt: CI\n\n.. |codecov-badge| image:: http://codecov.io/github/edx/help-tokens/coverage.svg?branch=master\n :target: http://codecov.io/github/edx/help-tokens?branch=master\n :alt: Codecov\n\n.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/help-tokens.svg\n :target: https://pypi.python.org/pypi/help-tokens/\n :alt: Supported Python versions\n\n.. |license-badge| image:: https://img.shields.io/github/license/edx/help-tokens.svg\n :target: https://github.com/openedx/help-tokens/blob/master/LICENSE.txt\n :alt: License\n\n\n\nChange Log\n**********\n\n..\n All enhancements and patches to help_tokens will be documented\n in this file. It adheres to the structure of http://keepachangelog.com/ ,\n but in reStructuredText instead of Markdown (for ease of incorporation into\n Sphinx documentation and the PyPI description).\n\n This project adheres to Semantic Versioning (http://semver.org/).\n\n.. There should always be an \"Unreleased\" section for changes pending release.\n\n[2.3.0] - 2023-08-02\n====================\n\n* Added support for Django 4.2\n\n[2.2.0] - 2022-01-20\n====================\n\n* Dropped support for django2.2, 3.0, 3.1 and 3.2\n* Added Django40 support in CI\n\n[2.1.0] - 2020-07-07\n====================\n\n* Added support for django3.0, 3.1 and 3.2\n\n[2.0.0] - 2020-01-19\n====================\n\n* Removed support of python3.5\n\n[1.1.0] - 2020-05-05\n====================\n\n* Removed support of Django < 2.2 version\n* Added support for python 3.8\n\n[1.0.3] - 2017-07-17\n====================\n\n* Updated tests to support Django 1.11\n* Updated dependency versions\n\n\n[1.0.2] - 2017-05-16\n====================\n\n* Fixed the README.\n\n\n[1.0.1] - 2017-05-15\n====================\n\n* First version on PyPI.\n\n\n[1.0.0] - 2017-05-03\n====================\n\n* First release.\n",
"bugtrack_url": null,
"license": "AGPL 3.0",
"summary": "Django app for linking to help pages with short tokens",
"version": "2.3.0",
"project_urls": {
"Homepage": "https://github.com/openedx/help-tokens"
},
"split_keywords": [
"django",
"edx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3cba4726caa51de05b160c6ce1ec40c27a1680d87dcc352598a95ccd00d77715",
"md5": "693d9ab790cc76a60a1b42dee14f985c",
"sha256": "7855c99b32a2427cffe3cc1d3dd9fa40466f0939339e7add57307e6d3813d27c"
},
"downloads": -1,
"filename": "help_tokens-2.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "693d9ab790cc76a60a1b42dee14f985c",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 19038,
"upload_time": "2023-08-02T20:40:46",
"upload_time_iso_8601": "2023-08-02T20:40:46.246458Z",
"url": "https://files.pythonhosted.org/packages/3c/ba/4726caa51de05b160c6ce1ec40c27a1680d87dcc352598a95ccd00d77715/help_tokens-2.3.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "773676c0923ca0f9e26ec4b93553695e56bd26eeb348fc8c4b01f763194f9ab6",
"md5": "3aaae83835c53f9e9de3477d00bc2175",
"sha256": "450a529b86e2a89bd0e7f270d95ae21c40869502420c8af75019456fc1154333"
},
"downloads": -1,
"filename": "help-tokens-2.3.0.tar.gz",
"has_sig": false,
"md5_digest": "3aaae83835c53f9e9de3477d00bc2175",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 21719,
"upload_time": "2023-08-02T20:40:47",
"upload_time_iso_8601": "2023-08-02T20:40:47.800725Z",
"url": "https://files.pythonhosted.org/packages/77/36/76c0923ca0f9e26ec4b93553695e56bd26eeb348fc8c4b01f763194f9ab6/help-tokens-2.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-02 20:40:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openedx",
"github_project": "help-tokens",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "help-tokens"
}
JSON
