Jun 16, 2015 Tag: TYPO3

A New Theme for Docs.TYPO3.Org

It’s time to switch to a new theme on docs.typo3.org. Read here about the development, how things are going and how to contribute.

Updated on Jun 29, 2016

Navigate this page:

Tip: WIP - work in progress! I’m typing while you’re reading. Don’t be surprised when content suddenly changes.

Preview

Now there’s a : See a preview of syntax highlighting as well:

See a preview of syntax highlighting in a new window

See a preview of the new theme in a new window:

See a preview of the new theme in a new window

Introduction

What is this?

Currently I’m working on a new theme for docs.typo3.org. This blogpost is the place where I keep my notes while developing. So don’t be surprised when this contents changes while you’re reading it.

Looking back

Development of docs.typo3.org started around 2011.

(...)

Problems:

  • suboptimal readability and user experience
  • Sphinx search doesn’t work anymore
  • Sphinx rendering and theming isn’t used correctly
  • We have absolute paths for css and js files

Situation today

Things have changed:

  • No need any more to be optically in sync with typo3.org
  • The web “has become much more responsive”
  • We are much more experienced with Sphinx

Let’s build on the Sphinx-ReadTheDocs-Theme

ReadTheDocs hosts documentation for the open source community. They have developed a beautiful theme named sphinx_rtd_theme for Sphinx documentation. It can be found on Github. Find more information in this blogpost.

And, moreover, it’s one of the builtin themes by now that Sphinx brings along.

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

Developing for TYPO3

Home of Development

The repository t3SphinxThemeRtd is the home of development.

Development
The development takes place at Github in TYPO3-Documentation/t3SphinxThemeRtd. This is a fork of the original Sphinx-ReadTheDocs-Theme.
Contact
Use the issue tracker to get in contact.
Issues
Send issues to Github
To do
We need to think about what branches we want to have for t3SphinxRtd. branches should be a ‘production’ branch which will be deployed automatically on docs.typo3.org.

Collaborate and Contribute

To join the development fork t3SphinxRtd and send pullrequests. Use the issue tracker for communication.

Resources

TYPO3 Styleguide

To be done

  • Introduce a switch for “We are on our server”. In that case we want to do a lot of things specially when rendering. For example, on the server we want to keep fonts and styles only once. Or use a postprocessor? And we want to have a top level navigation.
  • Develop a top level navigation for the documents as outlined in Thinking about the toplevel menu to reach other manuals.
  • DEPLOY build chain with the new theme to the server!
  • On the search page: The “Hide Search Matches” function should be there and clickable.
  • When the “Edit me on GitHub” button is shown, there is no “Show source” link. Let’s put a “Show source” link that’s always available into the fly out menu at the lower left.
  • Isolate highlight.css so we can use a styleswitcher for highlighting
  • Fill flyout menu at the bottom left with versions
  • Add PDF download link
  • Think about singlehtml (one page) version of a manual
  • Check @font-face instructions for TYPO3 Share font. Add *.eot, *.woff, *.otf?
  • Make sure the contents of a page can easily be understood by Solr
  • Add Discourse.

Already done

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

Cool Stuff

  • Hah, cool, I just noticed: Horizontal scrolling of tables is possible by touch on touch enabled devices!
  • Try the search: It definitely finds every match IN THIS PROJECT! It works, and it will work offline as well.

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:

Search in Firefox

Knowhow for the PyPi Package Maintainer

Tricky!

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

Thinking about the toplevel menu to reach other manuals

  1. A TYPO3 manual doesn’t come alone - we have many of them. So we need a way to choose and navigate from one to another.

  2. Here’s how the Ansible folks do it. They add a horizontal bar at the top:

    A screenshot showing how the Ansible folks added a toplevel menu
  3. I suggest we do the same for the TYPO3 manuals.

  4. Currently the toplevel menu FOR ALL EXISTING manuals is taken from this unique Javascript file: https://docs.typo3.org/js/docstypo3org-1.js To change a menu option we only have to change a single file.

  1. I suggest we keep on doing that. The tag to include the Javascript would be:

    <script src="/js/mainmenu.js"></script>
    
  2. The new t3SphinxThemeRtd theme knows a variable already that indicates whether the rendering is targeted for our server or not. I would say, only manuals on the server should have that toplevel menu.

    So the bar at the top will only exist if it’s a manual on the server. By default there’s just a single link pointing to the root “/” of the server. If Javascript is active that /js/mainmenu.js will decide about what happens to the bar at the top.

Opinions?

Comments

comments powered by Disqus

Previous topic

1001 Tips

Next topic

TYPO3 Documentation: What's Version 0.0?

Tags

Archives

Languages

Recent Posts

This Page