[TYPO3-doc] Help with the migration to reST

[Philipp Gampe]

Hi Martin,

Martin Bless wrote:
> I'm all with you. Its just that you are the first one who addresses
> this question: How can contributors run the Sphinx make process on
> their own machine the easiest way?
> 
> This would mean that we tell people:
> 
> - how to install Python, Docutils, Sphinx

Sure, but that is required anyway.

> - each documentation project (=manual, =git-repository) could and
> should have a Makefile and conf.py included that is tailored for that
> build process at home.

Yes, that is what I am talking about.

> - We should make the "typo3sphinxtheme" as Python package available
> that automatically integrates with Sphinx. Then everything can be
> nicely maintained on its own. No symlinks and so required. You would
> just do a "make(.bat)" in the appropriate folder. And have the result
> in "_build" as thats the default for Sphinx. And put "_build" in the
> .gitignore file.

Perfect.

So we need a git repository for this package (Documentation/TYPO3/Theme?). 
How long will it take you to create a first version with the current state 
of the theme?

> Security: We have to keep in mind that conf.py is actually a script
> that can do anything on your machine you have the right to. How to
> handle that? Maybe we should use a YAML config file for that within
> the documentation where the authors can configurate everything they
> need to (version, names, title, intersphinx mappings ...).

Thats not an argument. Only trusted people are allowed to commit to the 
repository. The rendering does not need much privileges on the server side, 
so the worst an attacker could do is to mess with the rendering ... easy to 
fix and clean up.

> For the same security reasons and because the Makefile and the conf.py
> may depend on the concrete versions and packages that are installed
> I'll be using a specific one on the server. That's why for example
> ./Tca.git.make/* is not versioned.

Version it in the rest tools repository. IMHO this is our dumping stuff and 
there it wont get lost.

I care so much about versionning, because I have seen many projects get 
stuck once somebody was not available any move for whatever reason.
A project should always be in a state that another person can take over at 
any time.

Cheers
-- 
Philipp Gampe – PGP-Key 0AD96065 – TYPO3 UG Bonn/Köln
Documentation – linkvalidator
TYPO3 .... inspiring people to share!