Django app for linking to help pages with short tokens
Project description
help-tokens
=============================
Django app for linking to help pages with short tokens.
|pypi-badge| |travis-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/edx/edx-platform/blob/master/CONTRIBUTING.rst>`_ 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 `PULL_REQUEST_TEMPLATE.md <https://github.com/edx/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/edx/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
.. |travis-badge| image:: https://travis-ci.org/edx/help-tokens.svg?branch=master
:target: https://travis-ci.org/edx/help-tokens
:alt: Travis
.. |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/edx/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.
[1.0.1] - 2017-05-15
~~~~~~~~~~~~~~~~~~~~
* First version on PyPI.
[1.0.0] - 2017-05-03
~~~~~~~~~~~~~~~~~~~~
Added
_____
* First release.
=============================
Django app for linking to help pages with short tokens.
|pypi-badge| |travis-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/edx/edx-platform/blob/master/CONTRIBUTING.rst>`_ 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 `PULL_REQUEST_TEMPLATE.md <https://github.com/edx/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/edx/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
.. |travis-badge| image:: https://travis-ci.org/edx/help-tokens.svg?branch=master
:target: https://travis-ci.org/edx/help-tokens
:alt: Travis
.. |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/edx/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.
[1.0.1] - 2017-05-15
~~~~~~~~~~~~~~~~~~~~
* First version on PyPI.
[1.0.0] - 2017-05-03
~~~~~~~~~~~~~~~~~~~~
Added
_____
* First release.
Project details
Release history Release notifications | RSS feed
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)
Built Distribution
Close
Hashes for help_tokens-1.0.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e5294b9663eb9cc68dcd6273ea323478389559ae4c86b82321d63dc8024dc1d8 |
|
MD5 | a9b4cc11e11420f572a9a3e57338a87a |
|
BLAKE2b-256 | d4ad0414c3f57f41d652b19665e371d8b5072cdf4b20fdb6a5b13eb24daaa92e |