Theme development

The following shows how to clone our theme for development, how to make it available in our Docker render container and how to render documentation using the new theme.

Prepare theme for development

Create a local folder to hold themes. Let's name that folder ~/THEMES:

mkdir ~/THEMES

Clone theme for development:

# garantee folder
mkdir -p ~/Repositories/github.com/TYPO3-Documentation

# go there
cd ~/Repositories/github.com/TYPO3-Documentation

# clone
git clone https://github.com/typo3-documentation/t3SphinxThemeRtd

Use npm, yarn, grunt, … to provide all resources and to run a build. For example:

cd ~/Repositories/github.com/typo3-documentation/t3SphinxThemeRtd

# install packages
yarn

# build
grunt

# At this point a new version of the theme should have been built

Example:

➜  t3SphinxThemeRtd git:(feature/abc) ✗ grunt
Running "clean:build" (clean) task

Running "clean:fonts" (clean) task
Cleaning t3SphinxThemeRtd/static/fonts...OK

Running "copy:fonts" (copy) task
Copied 40 files

Running "sass:build" (sass) task

Done, without errors.

Copy the new build to the THEMES folder, thereby giving it a name that is not in the list of available themes so far:

# WITH slash at the end of source!
source=~/Repositories/github.com/TYPO3-Documentation/t3SphinxThemeRtd/t3SphinxThemeRtd/

# WITH slash at the end of dest!
dest=~/THEMES/t3SphinxThemeRtdDevelop/

rsync -avii -delete $source $dest

#

So there should exist a new folder ~/THEMES/t3SphinxThemeRtdDevelop. In your documentation you have to specify that name as desired theme.

Use the dev theme

New in version v2.4.0.

Make THEMES available

Here we assume that the dockrun helper function is available. In a terminal window:

# turn some debug output on
T3DOCS_DEBUG=1

# point to your THEMES folder. If this envvar is set it will automatically
# be mapped into the container.
T3DOCS_THEMES=~/THEMES

# go to you project
cd ~/project

# use the container like normal
dockrun_t3rd

There should be output similar to the following. Note that you should see a mapping of the ~/THEMES folder:

PROJECT......: ~/project
creating: mkdir -p ~/project/Documentation-GENERATED-temp
RESULT.......: ~/project/Documentation-GENERATED-temp
THEMES.......: ~/THEMES
OUR_IMAGE....: t3docs/render-documentation:v2.4.0
docker run --rm --user=1000:1000 \
   -v ~/project:/PROJECT:ro \
   -v ~/project/Documentation-GENERATED-temp:/RESULT \
   -v ~/THEMES:/THEMES \
   t3docs/render-documentation:v2.4.0
t3rd - TYPO3 render documentation (v2.4.0)
For help:
   docker run --rm t3docs/render-documentation:v2.4.0 --help
   dockrun_t3rd --help

... did you mean 'dockrun_t3rd makehtml'?

Set up your documentation

You cannot specify your theme in Settings.cfg as that value gets overriden and will always be 't3SphinxThemeRtd' in the end.

You can set the theme in ./Documentation/jobfile.json however like so:

{
  "Overrides_cfg": {
    "general": {
      "html_theme": "t3SphinxThemeRtdDevelop"
    }
  }
}

Additionally theme options may be of special interest.

Attention: ANY non empty string is considered to be TRUE.

{
  "Overrides_cfg": {
    "html_theme_options": {
      "docstypo3org": "yes",
      "add_piwik": "yes",
      "show_legalinfo": "yes"
    }
  },
}

Attention: Use the empty string to specify FALSE.

{
  "Overrides_cfg": {
    "html_theme_options": {
      "docstypo3org": "",
      "add_piwik": "",
      "show_legalinfo": ""
    }
  },
}

Finally - use it like hell :-)

Start rendering and developing using normal procedures:

dockrun_t3rd  makehtml  -c jobfile /PROJECT/Documentation/jobfile.json