sphinx-typo3-theme 4.9.0
Sphinx TYPO3 theme for https://docs.typo3.org/
License: MIT license
Requires Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*


========
Overview
========

Sphinx TYPO3 theme for docs.typo3.org
=====================================


Sphinx TYPO3 theme contains all files required to build a Sphinx extension that
provides the theme.

* Maintainer: Martin Bless <martin.bless@mbless.de>
* Provided by the TYPO3 documentation team.
* Free software: MIT license
* Authors: See AUTHORS.rst
* Repository: https://github.com/TYPO3-Documentation/sphinx_typo3_theme
* Documentation: See docs/ folder and https://typo3-documentation.github.io/sphinx_typo3_theme/


Credits
-------

`Benjamin Kott`_ has created this theme from scratch without dependencies to
Sphinx themes or the `ReadTheDocs theme`_. Thank you very much, great work!

The ancestor of this package is `t3SphinxThemeRtd`_ which had been developed
by `Martin Bless`_ as a derivative of the ReadTheDocs theme.

.. _Benjamin Kott: benjamin.kott@outlook.com
.. _Martin Bless: martin.bless@mbless.de
.. _ReadTheDocs theme: https://github.com/readthedocs/sphinx_rtd_theme
.. _t3SphinxThemeRtd: https://github.com/typo3-documentation/t3SphinxThemeRtd


Releasing
---------
Make sure to specify all three numbers as in 'v99.88.77'.


Feature demonstration
---------------------

There also is a `demo manual <https://typo3-documentation.github.io/sphinx_typo3_theme_rendering_test/>`__
which serves as a "stress test" for the theme and shows what markup is possible and
how it gets rendered.


Development
-----------

We are using Ubuntu (22.04) for development with `Python3
<https://www.python.org/>`_ installed. Further we are using GNU `make <https://www.mankier.com/1/make>`_
for convenience.
Next we are using the `Node Version Manager (NVM)
<https://github.com/nvm-sh/nvm>`_ to install and activate Node version v12::

   ❯ nvm install 12
   ❯ nvm ls          # list installed version
   ❯ nvm use v12     # activate


We also need `Yarn <https://yarnpkg.com/>`_ and `Grunt
<https://gruntjs.com/>`_. Let's install these globally::

   ❯ npm install -g yarn
   ❯ npm install -g grunt

Clone the repository::

   ❯ git clone https://github.com/TYPO3-Documentation/sphinx_typo3_theme/

Further steps::

   ❯ cd sphinx_typo3_theme  # go there
   ❯ make                   # see what options you have
   ❯ cat Makefile           # read for understanding
   ❯ cat Gruntfile.js       # read for understanding

Use Node version v12, show Python version::

   ❯ nvm use v12
   Now using node v12.22.12 (npm v6.14.16)

   ❯ python --version
   Python 3.10.6

Install the Python modules, install the Node modules and build
everything::

   make setup buildall

Repeat as you like::

   make buildall

Look at folder `./dist` to find the build results::

   ❯ ls ./dist

Example output::

   ./dist/sphinx_typo3_theme-4.7.10.dev1+gc7ebb3d.d20230426-py2.py3-none-any.whl
   ./dist/sphinx_typo3_theme-4.7.10.dev1+gc7ebb3d.d20230426.tar.gz

You may study as well the GitHub workflows of this repository.

Restrictions
------------

This theme has not been used or tested with Sphinx versions that are
newer than Sphinx-4.5.0.

What else?
----------

Have fun!


===================
History / Changelog
===================

4.9.0 (2023-07-06)
==================

*  fbad57b Write 'Page last updated' instead of 'Last updated' in footer
*  3ffce30 Make admonitions less heavy issue #201


4.8.0 (2023-06-23)
==================

*  7b90e09 2023-06-23 Update-compact-list:
   If display width is > 992px long list of .toctree or .contents can be shown with no extra spacing between lines
   if `:class: compact-list` is set. This now also works for `.compact-list li > p`.

*  9f72698 2023-06-23 Style div.versionadded:
   The div block is indented now and has a vertical left bar.

*  fb34a94 2023-06-22 Update footer: If link to theme is shown, show link to DRC as well, if given.

*  efab638 2023-06-22 Reduce visual clutter for inline code

*  35f0e2d 2023-06-22 Make all three buttons open in a new window


4.7.10 (2023-05-08)
===================

*  1da63a0 2023-05-08 Update codeblock.css to not select linenos                                                                                                                             ─╯
*  b7b4603 2023-05-08 Fix and update workflow CI.yml
*  fbb1fee 2023-05-08 Update README.rst: add development how-to


4.7.9 (2022-09-23)
==================

*  Fix bug in html template


4.7.8 (2022-09-23)
==================

*  Provide ready made codeblocks.css for syntax highlighting in code blocks.
   It doesn't have dependencies and uses css variables
*  Add style switcher dark/light for code blocks
*  Update styling of .bignums


4.7.7 (2022-09-05)
==================

*  Rework syntax highlighting. Use css variables. Add codeblock.css as
   extra file.
*  Fix dl p issues
*  Update styling of dl lists


4.7.6 (2022-07-25)
==================

*  Make logo link to docs home work again
*  Remove one-to-much htmlescape of 'title' in breadcrumbs
*  Change confval styling as described in issue #170


4.7.5 (2022-07-13)
==================

*  Set v4.7.5 for Release v4.7.5


4.7.4 (2022-05-09)
==================

*  Fix typo (gitlab -> GitLab)


4.7.3 (2022-05-05)
==================

*  Fix html template error in breadcrumbs.html


4.7.2 (2022-05-04)
==================

*  Simplify Edit button definition, drop the bitbucket_*, github_*,
   gitlab_* variables, use edit_button_type, repository_url, repository_branch.
   See theme.conf, breadcrumbs.html


4.7.1 (2022-05-03)
==================

*  Improve css - beautify


4.7.0 (2022-04-25)
==================

*  Added: tag v4.7.dev to allow for better versions generated by setuptools_SCM
*  Add right margin in confval css


4.7.dev6 (2021-12-13)
=====================

*  Activate project links in the footer for all renderings, not just those for
   docs.typo3.org
*  Supplement and reorder variables in `theme.conf`
*  Add Python 3.10 as valid version in setup.py
*  Fix margin of nested .toctree lists
*  Remove margin of last <p> in table cells
*  Exclude line numbers from selects in code blocks


4.7.dev5 (2021-11-06)
=====================

*  Style caption of code-blocks
*  Update template extensions.html
*  Add generic classes bold-important, padding-0-important


4.7.dev3 (2021-11-02)
=====================

*  [FEATURE] Add displaysettingsui panel: Use full width, Make settings
   permanent
*  Mention DRC with link in footer, with DRC version
*  Improve Makefile, add 'buildall' target in Makefile
*  Style sphinx-tabs, phpdomain, confval, field-list
*  [FIX] Fix load order of css files to have our theme.css at the end
*  Update pygments.scss
*  [EVOLVE] Account for new <li><p> nesting of latest Sphinx
*  [EVOLVE] Disable overpowering style for <dl>
*  [EVOLVE] Remove margins from <p> within <li>, produced by latest Sphinx
*  Add 'black' to requirements_dev.txt
*  Update classifiers in setup.py
*  Add Javascript and html for 'versionhints'
*  Use searchtools.js from Sphinx 4.2.0
*  Update theme.js, load versionhints.html if applicable
*  9ff062b 2021-09-16 Upgrade all packages to current in yarn.lock
*  Use searchtools.js from Sphinx-4.1.2


4.6.1 (2021-07-21)
==================

*  [BUGFIX] Fix broken layout.html
*  Add theme variable global_search_action


4.6.0 (2021-07-19)
==================

*  Add global search to page template
*  Rearrange ux buttons "Edit on GitHub" and so on
*  Fix css in pr#133
*  Improve Gruntfile.js, Makefile, .jshintrc
*  Introduce .git-blame-ignore-revs
*  Introduce 'black' code formatter
*  Add 'black' badge to README.rst


4.5.2 (2021-03-26)
==================

*  Have 'How to edit' button point to `GithubMethod.html
   <https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocsOfficial/GithubMethod.html>`__

*  Always show the 'How to edit' button when the 'Edit on ...' button is shown

*  Built in offline Sphinx search autocompletion: Turn autoSelect off, use text
   'Not found in word stems'

*  Remove flex property from logo link, so that it doesn't extend the clickable
   area past the image


4.5.1 (2021-03-13)
==================

*  Remove current 'Switch panel' solution (not production ready).

4.5.0 (2021-03-12)
==================

*  Start with 'Switch panel'
*  Add 'How to edit' button
*  Start 'TYPO3 Exceptions' with collapsed menu


4.4.3 (2021-01-20)
==================

*  37af740 Raise full width break point from 1800px to 2049px


4.4.2 (2021-01-06)
==================

*  8b1f5c3 Style index page genindex.html (issue #99)


4.4.1 (2020-12-10)
==================

*  5fb7837 Fix css for images and figures


4.4.0 (2020-12-07)
==================

*  daf6211 [FEATURE] Provide for Sphinx extension sphinx-tabs


4.3.1 (2020-12-01)
==================

*  e67d144 Use max-width:100% for PlantUML objects


4.3.0 (2020-11-30)
==================

*  5ac9115 v4.3.0
*  d605a2c Update .compact-list, only for screens >=992px
*  e886449 Bring back .compact-list, remove Figure:
*  f56aeea Fix indent of nested .line-block
*  604eee1 Issue #14: Tweak $box-shadow-sm
*  7d52ca8 Enable sourceMap in Gruntfile.js
*  53012f5 Update yarn.lock - apply security updates reported by GitHub
*  0ffa575 Update flake8 exclude - don't check ``*GENERATED*`` files
*  1225ec1 Add styles .centered, .rubric - add css classes
*  14eea54 Update style p.attribution - style attribution in blockquotes
*  56bbb03 Update style .versionmodified - make 'versionadded' stick out
*  0610ae2 [FEATURE] Issue #80: Breakpoint to allow width:99999px - use total
   width for screens >= 1800px


4.2.1 (2020-05-20)
==================

*  Add PAGE CONTENTS above the menu of intra-page links


4.2.0 (2020-05-08)
==================

Overview

#. If used with Sphinx extension `sphinxcontrib-gitloginfo
   <https://github.com/TYPO3-Documentation/sphinxcontrib-gitloginfo/>`_ meta tags
   with the 'last modified' date may now be added to the page html head section.
   A 'Last updated' line can be shown in the footer with a link to the latest
   commit.

#. For search result pages a link will appear to deselect hightlighting of
   search text hits.

#. The intra page menu is now appended to the left menu column of the page.

#. The logo is now defineable in the theme configuration file `theme.conf`.

Some commits:

*  d5cc051 [BUGFIX] Supply missing options in theme.conf to remove warnings
   about non existing theme options
*  a69e91b [FEATURE] Always show table of contents {{ toc }} to get back
   "the third level" in the page menu
*  e5f8b9c [FEATURE] Add date_last_modified and commit_url to footer
*  14c3f6a Update whitespace control in html templates to further beautify the
   indentation of generated html
*  4da72be [FEATURE] Add last_updated_isoformat to meta data in html head
*  e1061a2 [TASK] Update docsearch meta tags
*  a6605e0 [FEATURE] Make logo defineable in theme.conf
*  9b25042, 54d580e Improve page template "layout.html"
*  cfb7081 Update documentation
*  5f8cd43 Upgrade Javascript packages
*  cbeac0c Have link "Hide Search Matches" appear on a page with the search
   result to turn off the highlighting of the hits of the searched text


4.1.3 (2020-02-25)
==================

*  Update documentation
*  Have {{ theme_version }} in page context


4.1.2 (2020-02-25)
==================

*  Fix workflow, adapt docs


4.1.1 (2020-02-24)
==================

*  a907b05 Update documentation
*  f6e0b22 Update python_requires in setup.py
*  94e0f8f Make installation via entry_points work
*  4282600 Simplify conf.py in workflow
*  a06ddbb Upload to CDN with as well


4.1.0 (2020-02-24)
==================

"Let's start" release

*  Elaborate workflow
*  Add Makefile
*  Add Python unit test
*  Add docs
*  Deploy docs to Github pages
*  Tune setup.py and 'version from repo' procedure


0.1.0 (2020-01-01)
==================

*  Starting development.