Testing HTML rendering for a reStructuredText TYPO3 extension documentation

comments

typo3 sphinx restructuredtext rest documentation

This is my approach to test a reStructuredText documentation for a TYPO3 extension.

I read through the various Wiki pages and compiled this little guide. I think it is a more lightweight approach instead of installing the TYPO3 extensions restdoc/sphinx into a TYPO3 instance.

Prerequisites

Download & extract virtualenv.

$ ./virtualenv-1.10.1/virtualenv.py myext_doc
$ cd myext_doc
$ source ./bin/activate
(myext_doc)$ pip install sphinx
(myext_doc)$ git clone git://git.typo3.org/Documentation/RestTools.git
(myext_doc)$ cd RestTools/ExtendingSphinxForTYPO3
(myext_doc)$ python setup.py install
Command line actions

Legend

Line 1: create virtualenv
Lines 2-3: activate virtualenv
Line 4: Install sphinx, follow sphinx quickstart guide at http://wiki.typo3.org/New_reST_Project_with_Sphinx
Lines 5-7: Install additional templates, see http://wiki.typo3.org/Rendering_reST_on_Linux#Installing_TYPO3_Templates for more information

html_theme = 'typo3sphinx'
html_theme_path = ['/path/to/your/virtuelenv/myext_doc/RestTools/ResourcesForSphinxAndDocutils/res/sphinx/themes/']
master_doc = 'Index'
source/conf.py adjustments

Add crosslinks/intersphinx references, see http://wiki.typo3.org/Tips_and_Tricks_%28reST%29#Cross-Links.

Write documentation

Write your documentation ;)

(myext_doc)$ make SPHINXOPTS="-a" html
SPHINXOPTS="-a" will force/update all files
for file in $(ls -R Documentation/*.rst Documentation/*/*.rst Documentation/*.txt); do sed -i '1s/^/\xef\xbb\xbf/' "$file"; done
BOMs get lost in Eclipse, this command will re-add them to the documentation files

Comments

comments powered by Disqus