Updating PropelBundle documentation

[javiereguiluz]

The Symfony project has decided to remove the chapter about Propel from the Symfony Book (details: symfony/symfony-docs#4900).

Similarly to DoctrineBundle, we want PropelBundle documentation to be managed on the bundle itself. Then we'll integrate the result in symfony.com documentation section to make it available to all Symfony developers.

We need some volunteer from the Propel community to do the work of importing the existing Propel documentation into this bundle. Thanks.

[weaverryan]

@havvg What do you think about this? Propel 1.x already has docs. So:

1. Do you have interest in integrating the symfony.com Propel docs, or do you think you already have basically the same information?

2. Do you have interest in the docs being hosted on symfony.com?

Thanks!

[havvg]

Hi @weaverryan,

I got some questions on this topic, to make a decision:

1. How do we reflect compatibility of the bundle version with Symfony versions in the documentation? Composer?
2. Is it possible to reflect different versions of this bundle on the Symfony documentation? Like a separate documentation of this bundle utilizing Propel 1.x and one for 2.x. - In other words, how may I setup the branches to take into account for documentation and process them independently, possibly cross-referencing my first question?

Currently I can only select the Symfony version of the documentation I want to read, which would be legacy part of the delegation of the documentation into this repository.

[weaverryan]

@havvg

1. There's nothing automated for this - but you could add a note right at the top that this version of PropelBundle is compatible with Symfony versions 2.3+ for example.
2. You can absolutely have however many version you want - check out FOSRestBundle for example: http://symfony.com/doc/master/bundles/FOSRestBundle/index.html. You can have multiple branches and those can be rendered as multiple version on there.

Cheers!

[havvg]

@weaverryan I'm +1 on this. The documentation is already available in this repository, is Markdown OK or am I required to convert it into rST?

What else is required to enable this? Deploying a new revision is only a commit on the correct branch, or is there any hook required?

[xabbuh]

@havvg As far as I know, rST is required. But we can help you if you prefer that. :)

@javiereguiluz Can you help with the other questions?

[weaverryan]

Agreed - it'll be RST-formatted. Once that's ready, @javiereguiluz will be able to put it up on the site. The versioning thing is not automatic yet - i.e. Javier will setup the branches that you need now, but if you need more branches in the future, we have to bother him :)

[havvg]

OK, I will convert the documentation into rST. Currently we only require two branches: 1.4 and 2.0.

[havvg]

@javiereguiluz I just created the documentation for the PropelAclBundle: https://github.com/propelorm/PropelAclBundle/blob/1.5/Resources/doc/index.rst (Not to be published, yet :))

Is there a staging environment or something alike, so I can view the results before pushing it? Maybe a vagrant box oder docker container for local use?

[javiereguiluz]

I'm closing this old issue because it's now outdated. Thanks!