edx-sphinx-theme
================
.. image:: https://img.shields.io/pypi/v/edx-sphinx-theme.svg
:target: https://pypi.python.org/pypi/edx-sphinx-theme/
:alt: PyPI
.. image:: https://github.com/openedx/edx-sphinx-theme/workflows/Python%20CI/badge.svg?branch=master
:target: https://github.com/openedx/edx-sphinx-theme/actions?query=workflow%3A%22Python+CI%22
:alt: GitHub CI
.. image:: http://codecov.io/github/edx/edx-sphinx-theme/coverage.svg?branch=master
:target: http://codecov.io/github/edx/edx-sphinx-theme?branch=master
:alt: Codecov
.. image:: https://readthedocs.org/projects/edx-sphinx-theme/badge/?version=latest
:target: http://edx-sphinx-theme.readthedocs.io/en/latest/
:alt: Documentation
.. image:: https://img.shields.io/pypi/pyversions/edx-sphinx-theme.svg
:target: https://pypi.python.org/pypi/edx-sphinx-theme/
:alt: Supported Python versions
.. image:: https://img.shields.io/github/license/edx/edx-sphinx-theme.svg
:target: https://github.com/openedx/edx-sphinx-theme/blob/master/LICENSE.txt
:alt: License
edx-sphinx-theme is a Sphinx theme for `Open edX`_ documentation. It should be
used for all documentation in repositories in the ``edx`` GitHub organization
which is intended to be used with the `Sphinx`_ documentation system.
.. _Open edX: https://open.edx.org/
.. _Sphinx: http://www.sphinx-doc.org/en/stable/
Overview
--------
This theme makes the following changes to the default Sphinx output:
* Displays the edX logo
* Adds a link to a feedback form that identifies which page the feedback came from
To use edx-sphinx-theme for a repository's documentation:
* ``pip install edx-sphinx-theme`` or equivalent (add ``edx-sphinx-theme`` to any appropriate requirements files)
* Add ``edx_theme`` to the ``extensions`` list in conf.py (it adds the feedback form URL to the rendering context for each page).
* Update the ``html_theme`` and ``html_theme_path`` values in conf.py so the theme can be located and loaded.
* Set ``html_favicon`` to the path of the favicon.ico file in the theme.
* Use the ``AUTHOR`` constant where appropriate in conf.py
(This default is only provided as a convenience. The repository is free to use another value if appropriate).
* To add an "Edit on Github" link to every page, add a dict called ``html_context``, as detailed in the following example.
For example:
.. code-block:: python
import os
import edx_theme
extensions = ['edx_theme']
copyright = '{year}, edX Inc.'.format(year=datetime.datetime.now().year)
author = edx_theme.AUTHOR
html_theme = 'edx_theme'
html_theme_path = [edx_theme.get_html_theme_path()]
html_favicon = os.path.join(html_theme_path[0], 'edx_theme', 'static', 'css', 'favicon.ico')
latex_documents = [
(master_doc, 'edx-sphinx-theme.tex', 'edx-sphinx-theme Documentation',
author, 'manual'),
]
html_context = {
"display_github": True, # Integrate GitHub
"github_user": "edx", # Username
"github_repo": 'edx-sphinx-theme', # Repo name
"github_version": "master", # Version
"conf_py_path": "/docs/", # Path in the checkout to the docs root
}
Read the Docs Configuration
---------------------------
Because this theme is a Python package which needs to be installed, `Read the
Docs`_ needs to be configured appropriately to be able to install it when
performing documentation builds. Under ``Advanced Settings``:
* ``Install your project inside a virtualenv using setup.py install`` should
be checked
* ``Requirements file`` should point to a pip requirements file which includes
``open-edx-theme``.
.. _Read the Docs: https://readthedocs.org/
Documentation
-------------
The full documentation is at https://edx-sphinx-theme.readthedocs.org.
License
-------
The code in this repository is licensed under the Apache Software License 2.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/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.
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
Change Log
----------
..
All enhancements and patches to edx-sphinx-theme 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.
3.1.0 --- 2021-01-17
~~~~~~~~~~~~~~~~~~~~
* Upgraded the `sphinx` version
3.0.0 --- 2021-07-01
~~~~~~~~~~~~~~~~~~~~
* Updated to the HTML generated by docutils 0.17. What had been ``<div
class="section">`` is now ``<section>``.
[2.1.0] - 2021-04-01
~~~~~~~~~~~~~~~~~~~~
* Adding "Edit on Github" button to breadcrums.
This should make it easier for viewers to easily correct or update bad documentation.
[2.0.0] - 2021-01-28
~~~~~~~~~~~~~~~~~~~~
* Dropped Python 3.5 Support
[1.6.1] - 2020-01-19
~~~~~~~~~~~~~~~~~~~~
* Fix the navigation section headers so that they are visible.
[1.6.0] - 2020-12-17
~~~~~~~~~~~~~~~~~~~~
* Updated the edX logo.
[1.5.0] -2019-06-19
~~~~~~~~~~~~~~~~~~~
* Requirements Update
[1.4.0] - 2018-12-04
~~~~~~~~~~~~~~~~~~~~
* Added support for the ``includehidden`` theme option. This shows a hidden toc
in sidebar.
* Upgraded many dependencies.
[1.3.0] - 2017-10-13
~~~~~~~~~~~~~~~~~~~~
* Added support for the ``navigation_depth`` theme option.
[1.2.0] - 2017-07-18
~~~~~~~~~~~~~~~~~~~~
* The text of the help and feedback links are now variables settable in the
html_context.
* Updated the copyright year.
[1.1.0] - 2017-06-28
~~~~~~~~~~~~~~~~~~~~
* Supply extension metadata to enable parallel builds.
[1.0.2] - 2016-11-09
~~~~~~~~~~~~~~~~~~~~
* Added favicon and .eot font file to distributed package.
[1.0.1] - 2016-10-14
~~~~~~~~~~~~~~~~~~~~
* Fixed two instances of line-height being slightly increased in an ugly way.
[1.0] - 2016-10-07
~~~~~~~~~~~~~~~~~~
Added
_____
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/openedx/edx-sphinx-theme",
"name": "edx-sphinx-theme",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Sphinx edx",
"author": "edX",
"author_email": "oscm@edx.org",
"download_url": "https://files.pythonhosted.org/packages/67/28/bbb1c485b1de723348e5f4ccc9e4213c003c02b0c670ccbf148af6ecd263/edx-sphinx-theme-3.1.0.tar.gz",
"platform": null,
"description": "edx-sphinx-theme\n================\n\n.. image:: https://img.shields.io/pypi/v/edx-sphinx-theme.svg\n :target: https://pypi.python.org/pypi/edx-sphinx-theme/\n :alt: PyPI\n\n.. image:: https://github.com/openedx/edx-sphinx-theme/workflows/Python%20CI/badge.svg?branch=master\n :target: https://github.com/openedx/edx-sphinx-theme/actions?query=workflow%3A%22Python+CI%22\n :alt: GitHub CI\n\n.. image:: http://codecov.io/github/edx/edx-sphinx-theme/coverage.svg?branch=master\n :target: http://codecov.io/github/edx/edx-sphinx-theme?branch=master\n :alt: Codecov\n\n.. image:: https://readthedocs.org/projects/edx-sphinx-theme/badge/?version=latest\n :target: http://edx-sphinx-theme.readthedocs.io/en/latest/\n :alt: Documentation\n\n.. image:: https://img.shields.io/pypi/pyversions/edx-sphinx-theme.svg\n :target: https://pypi.python.org/pypi/edx-sphinx-theme/\n :alt: Supported Python versions\n\n.. image:: https://img.shields.io/github/license/edx/edx-sphinx-theme.svg\n :target: https://github.com/openedx/edx-sphinx-theme/blob/master/LICENSE.txt\n :alt: License\n\nedx-sphinx-theme is a Sphinx theme for `Open edX`_ documentation. It should be\nused for all documentation in repositories in the ``edx`` GitHub organization\nwhich is intended to be used with the `Sphinx`_ documentation system.\n\n.. _Open edX: https://open.edx.org/\n.. _Sphinx: http://www.sphinx-doc.org/en/stable/\n\nOverview\n--------\n\nThis theme makes the following changes to the default Sphinx output:\n\n* Displays the edX logo\n* Adds a link to a feedback form that identifies which page the feedback came from\n\nTo use edx-sphinx-theme for a repository's documentation:\n\n* ``pip install edx-sphinx-theme`` or equivalent (add ``edx-sphinx-theme`` to any appropriate requirements files)\n* Add ``edx_theme`` to the ``extensions`` list in conf.py (it adds the feedback form URL to the rendering context for each page).\n* Update the ``html_theme`` and ``html_theme_path`` values in conf.py so the theme can be located and loaded.\n* Set ``html_favicon`` to the path of the favicon.ico file in the theme.\n* Use the ``AUTHOR`` constant where appropriate in conf.py\n (This default is only provided as a convenience. The repository is free to use another value if appropriate).\n* To add an \"Edit on Github\" link to every page, add a dict called ``html_context``, as detailed in the following example.\n\nFor example:\n\n.. code-block:: python\n\n import os\n import edx_theme\n\n extensions = ['edx_theme']\n\n copyright = '{year}, edX Inc.'.format(year=datetime.datetime.now().year)\n author = edx_theme.AUTHOR\n\n html_theme = 'edx_theme'\n html_theme_path = [edx_theme.get_html_theme_path()]\n html_favicon = os.path.join(html_theme_path[0], 'edx_theme', 'static', 'css', 'favicon.ico')\n\n latex_documents = [\n (master_doc, 'edx-sphinx-theme.tex', 'edx-sphinx-theme Documentation',\n author, 'manual'),\n ]\n\n html_context = {\n \"display_github\": True, # Integrate GitHub\n \"github_user\": \"edx\", # Username\n \"github_repo\": 'edx-sphinx-theme', # Repo name\n \"github_version\": \"master\", # Version\n \"conf_py_path\": \"/docs/\", # Path in the checkout to the docs root\n }\n\nRead the Docs Configuration\n---------------------------\n\nBecause this theme is a Python package which needs to be installed, `Read the\nDocs`_ needs to be configured appropriately to be able to install it when\nperforming documentation builds. Under ``Advanced Settings``:\n\n* ``Install your project inside a virtualenv using setup.py install`` should\n be checked\n* ``Requirements file`` should point to a pip requirements file which includes\n ``open-edx-theme``.\n\n.. _Read the Docs: https://readthedocs.org/\n\nDocumentation\n-------------\n\nThe full documentation is at https://edx-sphinx-theme.readthedocs.org.\n\nLicense\n-------\n\nThe code in this repository is licensed under the Apache Software License 2.0 unless\notherwise noted.\n\nPlease 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/edx-platform/blob/master/CONTRIBUTING.rst>`_ for details.\n\nEven though they were written with ``edx-platform`` in mind, the guidelines\nshould be followed for Open edX code in general.\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\nChange Log\n----------\n\n..\n All enhancements and patches to edx-sphinx-theme 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\n3.1.0 --- 2021-01-17\n~~~~~~~~~~~~~~~~~~~~\n\n* Upgraded the `sphinx` version\n\n3.0.0 --- 2021-07-01\n~~~~~~~~~~~~~~~~~~~~\n\n* Updated to the HTML generated by docutils 0.17. What had been ``<div\n class=\"section\">`` is now ``<section>``.\n\n[2.1.0] - 2021-04-01\n~~~~~~~~~~~~~~~~~~~~\n\n* Adding \"Edit on Github\" button to breadcrums.\n\n This should make it easier for viewers to easily correct or update bad documentation.\n\n[2.0.0] - 2021-01-28\n~~~~~~~~~~~~~~~~~~~~\n\n* Dropped Python 3.5 Support\n\n[1.6.1] - 2020-01-19\n~~~~~~~~~~~~~~~~~~~~\n\n* Fix the navigation section headers so that they are visible.\n\n[1.6.0] - 2020-12-17\n~~~~~~~~~~~~~~~~~~~~\n\n* Updated the edX logo.\n\n[1.5.0] -2019-06-19\n~~~~~~~~~~~~~~~~~~~\n\n* Requirements Update\n\n[1.4.0] - 2018-12-04\n~~~~~~~~~~~~~~~~~~~~\n\n* Added support for the ``includehidden`` theme option. This shows a hidden toc\n in sidebar.\n\n* Upgraded many dependencies.\n\n[1.3.0] - 2017-10-13\n~~~~~~~~~~~~~~~~~~~~\n\n* Added support for the ``navigation_depth`` theme option.\n\n[1.2.0] - 2017-07-18\n~~~~~~~~~~~~~~~~~~~~\n\n* The text of the help and feedback links are now variables settable in the\n html_context.\n\n* Updated the copyright year.\n\n[1.1.0] - 2017-06-28\n~~~~~~~~~~~~~~~~~~~~\n\n* Supply extension metadata to enable parallel builds.\n\n[1.0.2] - 2016-11-09\n~~~~~~~~~~~~~~~~~~~~\n\n* Added favicon and .eot font file to distributed package.\n\n[1.0.1] - 2016-10-14\n~~~~~~~~~~~~~~~~~~~~\n\n* Fixed two instances of line-height being slightly increased in an ugly way.\n\n[1.0] - 2016-10-07\n~~~~~~~~~~~~~~~~~~\n\nAdded\n_____\n\n* First release on PyPI.\n\n\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "A Sphinx theme for Open edX documentation",
"version": "3.1.0",
"split_keywords": [
"sphinx",
"edx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b73b653e5b29ded3c068968dfe93dd96586dbb71e561289ca01d458c2f8e840d",
"md5": "c7368e8f247e130d2442fd39d6068322",
"sha256": "d2902d700e2fef727e30c7bbf92d44cda633920f6760a1d7deb506dd29911060"
},
"downloads": -1,
"filename": "edx_sphinx_theme-3.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c7368e8f247e130d2442fd39d6068322",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 234159,
"upload_time": "2023-01-17T11:37:37",
"upload_time_iso_8601": "2023-01-17T11:37:37.780786Z",
"url": "https://files.pythonhosted.org/packages/b7/3b/653e5b29ded3c068968dfe93dd96586dbb71e561289ca01d458c2f8e840d/edx_sphinx_theme-3.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6728bbb1c485b1de723348e5f4ccc9e4213c003c02b0c670ccbf148af6ecd263",
"md5": "36d5b34ae2d8fd8bc6371daecad5f5a2",
"sha256": "a20272edf0a5938b218fae9ef9bf860e0f375d97bb87e7ca1579dd82038c9bea"
},
"downloads": -1,
"filename": "edx-sphinx-theme-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "36d5b34ae2d8fd8bc6371daecad5f5a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 238655,
"upload_time": "2023-01-17T11:37:39",
"upload_time_iso_8601": "2023-01-17T11:37:39.587444Z",
"url": "https://files.pythonhosted.org/packages/67/28/bbb1c485b1de723348e5f4ccc9e4213c003c02b0c670ccbf148af6ecd263/edx-sphinx-theme-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-17 11:37:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "openedx",
"github_project": "edx-sphinx-theme",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "edx-sphinx-theme"
}
JSON
