Documentation versioning

[Dalton Barreto]

Hello all,

The last stable released version of prestans is 1.0.3 [1], but the official documentation [2] points to version 1.1.

ReadTheDocs is able to build the documentation of all git tags of a repository, what do you think about tagging prestans doc repository?

Currently the doc repo has only the master branch, since ReadTheDocs always points to the "latest" docs we always get the 1.1 documentation. Currently, there is no easy way to read 1.0.3 docs.

But we can point the "latest" docs to the "current stable prestans release". To do this we could use gitflow [3] in the doc repo, that is, have two branches: master and develop.

We always develop the current docs in the develop branch and, synced with prestans release, we merge develop into master and create a tag. This way the master branch will always point to latest prestans release. We should also point the readTheDocs "latest" docs to the master branch (I thinks it's already pointed this way).

A last word about the maintainance of the "version" variable in docs/conf.py: Since the doc repo and the source-code repo are separated, currently we must always keep this value in sync with the current release. If you want, joining the two repos is a viable option. This way we can do something like this inside docs/conf.py.

sys.path.insert(0, '../')

from prestans import __version__

version = __version__

This way, building the docs will always have the right version, that is, the same version of the current developed prestans.

This joining can be done in both places, docs+prestans on github or docs+prestans on google code's svn.

So, what do you think? Makes sense? =D

Thanks,

[1] https://crate.io/packages/prestans/

[2] http://docs.prestans.org/en/latest/

[3] https://github.com/nvie/gitflow

--

Dalton Barreto
http://daltonmatos.com

http://wsgid.com/

[Devraj Mukherjee]

Hi Dalton,

My bad :) When we packaged up the 1.0.x branch for release I completely forgot to tag the documentation. At the time I was also in the middle of moving docs to Github, ReadtheDocs just works better with git.

On Fri, Feb 15, 2013 at 12:12 PM, Dalton Barreto <dalto...@gmail.com> wrote:

The last stable released version of prestans is 1.0.3 [1], but the official documentation [2] points to version 1.1.

1.1 documentation should work for 1.0.3 expect the API blueprint feature.  As you know we are considering a move to Github, hence we are in a state of flux.

Our plan is to push ahead with a 1.1 release and get the documentation up to scratch as part of that release. If you can bare with us for a few weeks we will get it all together to ensure a better future for prestans.

 

A last word about the maintainance of the "version" variable in docs/conf.py: Since the doc repo and the source-code repo are separated, currently we must always keep this value in sync with the current release. If you want, joining the two repos is a viable option. This way we can do something like this inside docs/conf.py.

Thanks for that tip, it will assist as we move forward.

Getting there! And appreciate your continued interest in prestans and we are working as hard as possible to streamline everything.

[Dalton Barreto]

Thank you very much! I will continue to keep an eye on prestans!

2013/2/15 Devraj Mukherjee <dev...@gmail.com>

--
You received this message because you are subscribed to the Google Groups "prestans-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prestans-discu...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.