[TYPO3-english] How to create backend module for documentation

[Sergio Catalá]

Hi Xavier,

Thanks for your long explanation! "sphinx" is a very useful extension (I 
could test it on your seminar on Developer Days in Hamburg) and it is 
making my life easier to write documents for my project right now :)

Your solution about frameset works, but the problem is the Html 
generated with "sphinx" in my local 6.1 installation contains wrong 
paths to Css and Js files. If I want to export this whole Html project 
(it has a lot of subfolders, it is not a standalone Html), and put the 
"_images" and "_static" folders into my extension "Resources/Public" 
folder, I should update all my Htmls to these new paths. I don't know if 
there is a better solution for this, as I am gonna update my 
documentation these days constantly.

Regards,
Sergio


On 31/10/13 11:40, Xavier Perseguers wrote:
> Hi Sergio,
>
>> to export all these Htmls to be presented nice. I just tested your
>> solution, adding all my Html documentation to
>> "my_extension/Resources/Private/Templates/Class/" and link it there, but
>> the Css doesn't apply just because of the paths.
> I don't understand, my solution must work, but you really need to use a
> frameset, you cannot just return the HTML. Basically it will show you
> exactly what you have when you point your browser to:
>
> http://yoursite/typo3conf/my_extension/Resources/Private/Templates/Class/your-doc.html
>
> as the HTML version of a Sphinx documentation is a standalone pure html
> website. Of course, you should logically put it under "Resources/Public"
> but that's not the problem here unless you deny access to
> Resources/Private in your Apache/Nginx configuration.
>
> So I guess you must have missed something because it *will* work.
>
>> I would like to find a nicer solution for that.
>>
>> Isn't there a chance to sphinx and restdocs are backwards compatible
>> with TYPO3 4.7? :(
> My Sphinx extension will not be backward compatible with 4.7, no. Sorry
> but I'm using namespaces everywhere and I don't want to double the
> amount of code or rely on pre-namespace classes from 4.x.
>
> If you read
> http://docs.typo3.org/typo3cms/extensions/sphinx/ChangeLog/Index.html
> you'll see that EXT:sphinx version 0.0.1 which has not been released to
> TER but as been tagged in (back then) SVN repository is compatible with
> TYPO3 4.5-4.7. It is very old and you will not get much more than a
> basic Sphinx environment that you may then use yourself to compile doc,
> but it should work (at least it worked for me in 4.x).
>
> EXT:restdoc is compatible with 4.5 to 6.2, just as stated in TER:
>
> http://typo3.org/extensions/repository/view/restdoc
>
> and I do not plan to drop support for TYPO3 4.x as long as it is still
> supported (thus 4.5 LTS end of life).
>
> So the idea is in fact that you compile your documentation as JSON (*not
> HTML*) either on 6.x with EXT:sphinx or yourself with your own Sphinx
> environment (locally, ...) and then you copy the generated documentation
> the way you want to a 4.x website and thanks to EXT:restdoc you can
> easily embed it into your website.
>
> If you want to embed it into the Backend, just as I did generically with
> the Sphinx Documentation Viewer from EXT:sphinx, just have a look at how
> I did it, there is no dependency on EXT:sphinx itself, it's just a use
> of the EXT:restdoc API, which thus works under TYPO3 4.x
>
> Kind regards
> Xavier
>