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

[Cameron Shorter]

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 list
> Live-demo at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/live-demo
> http://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 Source
http://www.lisasoft.com

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/live-demo/attachments/20110701/b37fd22a/attachment-0001.html