Metadata-Version: 1.1
Name: help-tokens
Version: 2.0.0
Summary: Django app for linking to help pages with short tokens
Home-page: https://github.com/edx/help-tokens
Author: edX
Author-email: oscm@edx.org
License: AGPL 3.0
Description: ###########
        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/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
        
        .. |ci-badge| image:: https://github.com/edx/help-tokens/workflows/Python%20CI/badge.svg?branch=master
            :target: https://github.com/edx/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/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.
        
        
        [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.
        
Keywords: Django edx
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 2.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
