search

TYPO3-Documentation / t3SphinxThemeRtd

Please report only issues that concern the rendering of the official TYPO3 docs here. For help and support on TYPO3, please see: https://typo3.org/help/
MIT License
11 stars 7 forks source link

readme

============================== A new theme for Docs.TYPO3.Org

:Project: t3SphinxThemeRtd :Team: TYPO3 Documentation Team :Author: Martin Bless martin.bless@typo3.org :License: MIT :Demo: See this demo docs t3SphinxThemeRtdDemoDocs <https://docs.typo3.org/typo3cms/drafts/github/TYPO3-Documentation/t3SphinxThemeRtdDemoDocs/>__ which are kind of a "stresstest" and demonstrate what's possible and how the theme can be used.

This work builds on top of v0.1.8 of https://github.com/snide/sphinx_rtd_theme <https://github.com/snide/sphinx_rtd_theme>__.

Find notes about the state of development in this blogpost <http://mbless.de/blog/2015/06/16/a-new-theme-for-docs-typo3-org.html>__.

Navigate this page:

.. default-role:: code

.. contents:: :local: :depth: 3 :backlinks: top

Installation

Install the Theme Using PIP

PIP <https://pip.pypa.io/en/stable/> is the Python <https://www.python.org/> packet manager for PyPi <https://pypi.python.org/pypi>__. 't3SphinxThemeRtd' is provided by the TYPO3 Documentation Team and available from PyPi.

Installation with pip::

fetch from PyPi and install latest version:

pip install --upgrade t3SphinxThemeRtd

if required for your system, run a superuser:

pip install --upgrade t3SphinxThemeRtd

For your interest: Some quick examples of pip usage::

find help

pip install --help pip --help

install locally for this user only

pip install --upgrade --user t3SphinxThemeRtd

uninstall - no matter if installed by PIP or setup.py:

pip uninstall t3SphinxThemeRtd

search PyPi, the Python packet index

pip search t3SphinxThemeRtd pip search sphinx

Install directly using 'setup.py'

To install directly from the package::

git clone https://github.com/TYPO3-Documentation/t3SphinxThemeRtd.git cd t3SphinxThemeRtd (sudo) python setup.py install

or install locally in user's home:

python setup.py --user install

Usage

In the conf.py file of your documentation project:

Load the module::

import t3SphinxThemeRtd

Choose the theme::

html_theme = "t3SphinxThemeRtd"

Set the theme path::

html_theme_path = [t3SphinxThemeRtd.get_html_theme_path()]

Or, if that's better in your case, add the theme path to to the list of already defined paths::

html_theme_path = []

...

html_theme_path.append(t3SphinxThemeRtd.get_html_theme_path())

Special Information for TYPO3 Users

  1. Disable or remove any existing "TYPO3 codeblock"

    If the "TYPO3 codeblock" is part of your conf.py file then you need to remove or disable that code. You can do that easily by writing if 0 instead of if 1.

    .. figure:: Documentation/Images/disable-typo3-codeblock.png :alt: How to disable an existing TYPO3 codeblock in conf.py

    Disable any "TYPO3 codeblock" in your conf.py by writing if 0.

  2. Once the "TYPO3 codeblock" is disabled the old t3sphinx module <https://git.typo3.org/Documentation/RestTools.git/tree/HEAD:/ExtendingSphinxForTYPO3/src/t3sphinx>__ IS NOT used any more. So you finally are being freed from old ballast and some of those old and annoying errors are gone. Rendering of Sphinx Json format will just work fine with the new theme.

  3. On the other hand: Since the t3sphinx module isn't loaded any more there is no processing of Yaml files for configuration at the moment. This means, at least for now:

    • You have to use a conf.py file for configuration.
    • You need to move all necessary settings from possible GlobalSettings.yml and Settings.yml files into the conf.py.

  4. Maybe we add Yaml processing in the future. At the moment this doesn't exist.

  5. To quickly get going: Feel free to copy from this Typoscript Reference conf.py example file <Documentation/Examples/TyposcriptReferenceExample-conf.py>__. The relevant parts are at the end.

To be done

Check this list in the blogpost <http://mbless.de/blog/2015/06/16/a-new-theme-for-docs-typo3-org.html#to-be-done>__

Already done

Check this list in the blogpost <http://mbless.de/blog/2015/06/16/a-new-theme-for-docs-typo3-org.html#already-done>__

How the Table of Contents builds

Read about this in the original README <https://github.com/snide/sphinx_rtd_theme>__.

Contributing or modifying the theme

This chapter is taken from the original README <https://github.com/snide/sphinx_rtd_theme>__ (and then modified)::

The t3SphinxThemeRtd is primarily a Sass <http://sass-lang.com/> project that requires a few other Sass libraries. We are using yarn to manage these dependencies and Sass to build the css. The good news is that there is a nice set of Grunt <http://gruntjs.com/> operations that will not only load these dependencies, but watch for changes, rebuild the sphinx demo docs and build a distributable version of the theme. The bad news is this means you'll need to set up your environment similar to that of a front-end developer (versus that of a python developer). That means installing Node <https://nodejs.org/>__.

Setup minimal development environment

  1. Install Node

  2. Install Yarn::

    npm install yarn

  3. Install project dependencies::

    yarn install

  4. Compile::

    yarn build

  5. Serve::

    yarn serve

End of README.