[Live-demo] Enhancement for Version number in Online Documentation

[Frank Gasdorf]

OK, just fixed the version read from VERSION.txt in conf.py and updated
html_tilte property - in the title was still v4.5 instead of the current
version.

I tried it on mac os but the arguments for sphinx-build command where not
used like I thought it would. Therefore the python conf.py update to read
from version file instead of parameters for sphinx-build command in Makefile

In addition I searched all 'OSGeo Live' occurrences and replaced it with
OSGeo-Live.

Last but not least I updated the copyright to 2011.

Cheers, Frank

2011/7/1 Cameron Shorter <cameron.shorter at gmail.com>

> **
>
> Thanks Frank for digging into this.
> My comments inline.
>
>
> On 1/07/2011 5:42 PM, Frank Gasdorf wrote:
>
> Hello,
>
>  I'd like to get feedback for little enhancements for the OSGeo Live
> Documentation.
>
>  Right now Makefile for the online docs replaces "OSGeo-Live" with
> OSGeo-Live <versionnumber> in all resulting html files as a post process
> after sphinx generated html files. After a grep of all *.rst files in the
> English sub folder with the regular expression "OSGeo.Live" the resulting
> list has two different versions of this String : OSGeo-Live and OSGeo Live.
>
>  Therefor not everywhere is the version number concatenated, which leads
> me directly to the proposal:
>
>  First I'd like to update the Makefile in a way, that the predefined
> variables release and version should be used to build html's [1].
>
>
> Good idea. Feel free to implement this.
>
>  Second I'd like to discuss, whether it is required to have the version
> number everywhere.
>
>
> Again, good idea to only use the version in the title. Feel free to
> implement.
>
>
>  IMHO we should use the *html_title* option (Default is "<project>
> v<release> documentation" and change it to "<project> <version>
> documentation".
>
>
> I'm not sure how this works, but if you have worked it out, I trust your
> judgement.
>
>
>  Third I'd like to ask you, what is :Version: in most of the rst-files
> for? Some have osgeo-live4.0, some osgeo-live4.5 and some files don't have
> this metadata at all. Maybe we could synch all files and update to :Version:
> |version|
>
>
> They were originally to note what was the version of osgeo-live when the
> docs were created. However, as you have picked up, the field has not been
> getting updated.
> I suspect it would be better to remove this field all together from all
> docs. If no one else objects within 48 hours. Feel free to remove this field
> in all docs.
>
>
>
>  Correct me, if I'm wrong: Is it right that the online docs are build with
> the Makefile in this way:
>
> make html
>
>
> docs are made by calling:
> bin/install_main_docs.sh
> which calls "make html"
>
>
>  in the root doc folder? Is the conf.py still required or just an old
> artifact not used anymore?
>
>
> I'm not sure. If you remove it, and the build still works, then it probably
> isn't being used and can be removed.
>
>
>
>  And what do you think about a version number in the header (right behind
> the banner) or footer. Nobody has to care about |version| right behind
> OSGeo-Live/OSGeo Live in the rst files anymore, translators should not care
> about these details ...
>
>  To get a clue what I'm writing about I attached a patch for you of the
> Makefile to review. I'm looking for your feedback!
>
>
> Feel free to commit your proposed fixes to svn. If there are issues, then
> we have enough time correct them.
> I'll check the docs and comment after you have committed the changes.
>
>
>  Thanks,
> Frank
>
>
>  [1] : http://sphinx.pocoo.org/config.html#project-information
>
>
> _______________________________________________
> Live-demo mailing listLive-demo at lists.osgeo.orghttp://lists.osgeo.org/mailman/listinfo/live-demohttp://wiki.osgeo.org/wiki/Live_GIS_Disc
>
>
>
> --
> Cameron Shorter
> Geospatial Solutions Manager
> Tel: +61 (0)2 8570 5050
> Mob: +61 (0)419 142 254
>
> Think Globally, Fix Locally
> Geospatial Solutions enhanced with Open Standards and Open Sourcehttp://www.lisasoft.com
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/live-demo/attachments/20110702/25a33343/attachment.html