[TYPO3-english] Bye-bye OpenOffice, welcome ReST

Xavier Perseguers xavier at typo3.org
Sat Aug 24 21:09:50 CEST 2013


Hello Peter,

> Show "Documentation Static" works, but Show Documentation Interactive throws the following error: 
> 
> Cannot build Sphinx project:
> --- snip ---
> copying static files... </span>done
> 
> <span style="color:#dc143c">Exception occurred:</span>
>   File "/Users/peter/Sites/typo3_61/typo3conf/ext/sphinx/Resources/Private/sphinx/1.1.3/lib/python/Sphinx-1.1.3dev_20130824-py2.7.egg/sphinx/builders/html.py", line 1017, in handle_finish
>     StandaloneHTMLBuilder.handle_finish(self)
> TypeError: unbound method handle_finish() must be called with StandaloneHTMLBuilder instance as first argument (got JSONHTMLBuilder instance instead)
> <span style="color:#dc143c">The full traceback has been saved in /var/folders/06/3nnlhj248xj1gv0059bj59v00000gn/T/sphinx-err-NBrcE0.log, if you want to report the issue to the developers.</span>
> Please also report this if it was a user error, so that a better error message can be provided next time.
> Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
> or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
> 
> I tried it with two different projects, i got this error in both. 

The problem is the t3sphinx theme which is not compatible with JSON
output: http://forge.typo3.org/issues/48087

I use a trick to prevent this problem so it seems it does not work in
your case. Please open a ticket in bug tracker (one from "sphinx") and
describe exactly how to reproduce (kickstart here, compile there, ...).

> Kickstarting a new project with Sphinx results in a somewhat different file structure as kickstarting with extension builder. 
> 
> In your documentation (http://docs.typo3.org/typo3cms/extensions/sphinx/UsersManual/DocsTypo3Org/Index.html) you write that there should exist a Settings.yml, but the extension builder does not make one. I presume this file is not necessary but recommended? I understand that it overwrites some default configuration, so of course it is usefull. 

Yes, Settings.yml overrides a few settings from conf.py which you don't
have for extensions as it is rendered on docs.typo3.org (well "will
be"). It only makes sense for extension manuals.

> "The PDF of your documentation is rendered using the LaTeX builder from Sphinx (seeRendering PDF from reStructuredText if needed) and should be explicitly activated for your extension. "
> => if there is no section "latex_documents:"  in Settings.yml there will no pdf rendered on docs.typo3.org? 

You understand it right! PDF rendering has to be explicitly activated
(ideally first testing locally that it actually compiles :D)

> Multilingual documentation: 
> "kickstart a new Sphinx project (incl.Settings.yml) within directory Documentation/Localization.<locale>."
> 
> So the folder should look like: 
> 
> myExt/Documentation/Localization/de_DE/
> 
> is this correct? 

No:

myExt/Documentation/Localization.de_DE/

> The given folder-struction coming from extension builder looks like: 
> 
> myExt/Documention/de_DE/

the folder structure is thus wrong, please open a bug ticket for
extension builder.

The outcome of the multilingual discussion may be found here:
http://forge.typo3.org/issues/50757

> and the links to the documentation online does not contain the folder /Localization/
> 
> http://docs.typo3.org/typo3cms/extensions/sphinx/fr-fr/_pdf/ (PDF).

No, the "/Localization.<locale>/" folder is just a way for us to see
that localization is present with no risk to mix-up the folder name with
a real (untranslated) chapter folder. We then extract the locale solely
to generate the translated documentation in a dedicated folder.

> I presume the directory should be: 
> 
> "kickstart a new Sphinx project (incl.Settings.yml) within directory Documentation/<locale>"

No, as said, stick to the documentation and create it within
Documentation/Localization.<locale> :)

Kind regards

-- 
Xavier Perseguers
Release Manager TYPO3 4.6

TYPO3 .... inspiring people to share!
Get involved: http://typo3.org



More information about the TYPO3-english mailing list