[TYPO3-doc] Help with the migration to reST

[Martin Bless]

Hi Philipp,

a lot of ToDos!

>Sorry for being so picky about this, but it is really important to me that 
>the whole documentation rendering is reduced to simple steps for 
>contributers.

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

- 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.

- 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.

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 ...).

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.

Yes, we are making progress: You can easily tell this from the speed
at which we a generating new tasks once one has been solved. Couldn't
be better!

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de