A New Theme for Docs.TYPO3.Org¶

General benefits of sphinx-rtd-theme¶

Modern, proven, maintained, well known, commonly used, beautiful, finetuned, covers most of the reST- and Sphinx HTML constructs, comes with “demodocs” right away.

Technical benefits¶

Uses opensource and documented components: Bourbon, Neat, Wyrm

Uses modern techniques: Bower, Github, Grunt, Livereload, Npm, Sass

TYPO3 Styleguide¶

• TYPO3 designteam - channel at Slack
• TYPO3.styleguide - a repository at Github
• TYPO3_Printstyleguide.pdf: Early beta version by the designteam

Versioning¶

• Semantic versioning, Python PEP about versioning

Syntax Highlighting¶

Best choice:

• Pick a template and a data file from the Base16 Builder and write our own Sass or Scss file
• Watch the following sites for good examples

Possible and recommended color schemes:

• 10 Vim Color Schemes You Need to Own
• Base16 Builder - this is it !!!
• KATzCool2 - a custom color scheme for PHPStorm, see blogpost
• prism - looks nice at first sight. Needs more contrast
• Smyck
• Solarized
• Tomorrow theme
• Darkula (like in PhpStorm)
• http://jmblog.github.io/color-themes-for-highlightjs/
• https://github.com/dwayne/sass-pygments/
• https://highlightjs.org/
• Twilight: http://www.colorschemer.com/schemes/index.php?tag=twilight

Bunch 3¶

Until 2015-09-16

• Lots of (style) improvements for t3SphinxThemeRtd. Release 3.2.0.
• Make “Edit me on GitHub” button look nicer
• Publish v3.1.0
• Use minified jQuery
• Add “Edit me on GitHub” button
• Publish v3.0.0 to PyPi. And find out how that works.

Bunch 2¶

Until 2015-06-30

• Done: Published initial version at https://github.com/TYPO3-Documentation/t3SphinxThemeRtd We are starting with version number 3.0.0
• Done: Cleaned everything up and pushed to Git
• Done: Cleanup the SourceSansPro files in Grunt and Sass
• Done: Added SourceCodePro stuff to Bower, Grunt, Sass
• Done: Add autocompletion to the Sphinx search
• Done: Sphinx search doesn’t find parts of words. Investigate! Answer: It’s a feature, not a bug, I would say.
• See this experimental rendering of the Typoscript Reference. Search has autocompletion but doesn work perfectly yet.
• Change highlighting color scheme to something derived from ‘prism’. Publish as TSRef 0.0 and send tweet.
• Show how we can implement OpenSearch. See chapter About OpenSearch below.
• Done: Find out what we need to do to add OpenSearch, see this
• Show a first experimental version of a real manual online (TyposcriptReference)
• Give generic admonition correct styling too
• Use TYPO3-key-color for .wy-nav-top for media(small)

Bunch 1¶

Until 2015-06-18

• Have ‘sidebar’s stay beneath by adding ‘clear:both’ for h1, h2 in +media(desktop)
• Investigation: Explore how to best implement a CSS styleswitcher. See notes at Change CSS by Javascript
• Add a detailed demo page for syntax highlighting! Cool ...
• Obsolete: Check whether there is a sass file for the darkula theme.
• Add Sass and Scss files to integrate syntax highlighting nicely and flexible
• Add TYPO3.styleguide to Bower packages
• Cool: Base16 Builder seems to be a great and flexible solution for syntax highlighting color schemes!
• Checked: The dark background of ‘solarizeddark’ highlighting doesn’t fit at all
• Use 1600px instead of 800px for maximum width
• Remove hover color from TYPO3 logo
• Show a preview of the new theme in the blogpost
• Start writing a blogpost about the theme development
• Do first experiments “solarized” syntax highlighting
• Add ‘t3tablerows’ examples to the demo docs
• Add color demo code to the demo_docs
• Add admonition examples to the demo_docs
• Start tweaking colors in sass. Deploy colors from TYPO3_Printstyleguide.pdf
• Add TYPO3 color constants to sass files
• Firefox doesn’t scale the logo properly. Add fix to css.
• Add typo3-white.svg as logo
• Add Source Sans Pro font to sass and css for continuous text
• Add TYPO3 Share font for headlines
• Find out how the menu is generated from the ‘toctree’ directive
• Create the ‘t3SphinxRtd’ home repository
• Contact the TYPO3 designteam
• Recherche

About OpenSearch¶

We can add OpenSearch! This is how it can look like.

Firefox offers option¶

Firefox offers and action to add the search of the manual to the list of permanently available search machines:

New search option¶

Create a settings file .pypirc in your home folder¶

[distutils]
index-servers =
   pypi
   pypitest

[pypi]
repository = https://pypi.python.org/pypi
username = marble
password = A-GOOD-PASSWORD

[pypitest]
repository = https://testpypi.python.org/pypi
username = marble
password = A-GOOD-PASSWORD

Do some training with the TestPyPi¶

See https://wiki.python.org/moin/TestPyPI

Register the project at ‘testpypi’:

# the easy way - but not secure
python setup.py register -r https://testpypi.python.org/pypi

Build a wheel-distribution:

python setup.py bdist_wheel --universal

Upload securely:

twine upload dist/*  -r pypitest

Uninstall existing versions:

pip uninstall t3SphinxThemeRtd

Search at testpypi:

# This should work but didn't when I tried immediately
# after uploading. It seems it takes a while.
pip search --index https://testpypi.python.org/pypi t3SphinxThemeRtd

Do a test-install from testpypi:

pip install --user -i https://testpypi.python.org/pypi t3SphinxThemeRtd

# verify that it has been installed and can be found
cd somewhere/else
python -c "import t3SphinxThemeRtd; print t3SphinxThemeRtd.__file__"

First real upload to PyPi¶

Register the project at ‘pypi’:

# the easy way - but not secure
python setup.py register

Build a wheel-distribution:

python setup.py bdist_wheel --universal

Upload securely:

twine upload dist/*

Uninstall existing versions:

pip uninstall t3SphinxThemeRtd

Search at testpypi:

# This should work but didn't when I tried immediately
# after uploading. It seems it takes a while.
pip search t3SphinxThemeRtd

Install using PIP:

pip install t3SphinxThemeRtd

# verify that it has been installed and can be found
cd somewhere/else
python -c "import t3SphinxThemeRtd; print t3SphinxThemeRtd.__file__"

Real upload of next version to PyPi¶

Go to where you’ve cloned the reposiory:

cd ~/Repositories/github.com/TYPO3-Documentation/t3SphinxThemeRtd

Remove old builds:

rm -rf dist/*

Build a wheel-distribution:

python setup.py bdist_wheel --universal

Upload securely:

twine upload dist/*

Test the download, but don’t actually install:

# go somewhere
cd temp/

# download latest version to current folder

# was:
# pip install t3SphinxThemeRtd --upgrade --download .

# pip now has a download command:
pip download t3SphinxThemeRtd