[Live-demo] New Docs Plan

[Cameron Shorter]

On 21/07/10 16:03, Hamish wrote:
> Alex Mandel wrote:
>    
>> So I think I'm a little lost on the docs and hoping someone
>> can outline the plan so I know where to jump in and work on
>> the css.
>>
>> Are we replacing the descriptions with stuff generated from rst?
>>      
> AFAIK we're replacing the<project>_description.{html|odt} with
> <project>_overview.rst
Correct.

It would be greatly valuable if one person could go through all the 
applications and create one screenshot for each application, which can 
then be used by everyone creating overviews.

This will save editors needing to fiddle around creating screenshots.

  (If projects don't like their screenshot, then can create another one 
later).

I was originally hoping to create PDF docs out of this process, but so 
far the PDF's I've created have not been laid out very well, so I think 
we will have to wait until the next release to sort out PDFs, and just 
focus on HTML for the moment.

>   and<project>_quickstart.rst.
Project Quickstarts are highly encouraged, but not mandatory for this 
release, as we have not given people enough time to create them all. The 
test pages may have a good start for this material.
>   The very
> short<project>_definition.html chunks will remain (maybe to
> become part of the index page? apparently some more work is
> done there).
>    
I'm considering moving <project>definition html snippets, to a .rst 
snippet, which can then be aggregated into an index.html. I'm hoping to 
look into this over the next few days.

>    
>> Are the tests still being pulled from the Testing wiki page?
>>      
> That would make sense.
>    
Yes. The test descriptions should be made simpler by just saying "Run 
the QuickStart" for projects with a QuickStart.

>    
>> Is the rst being generated to static html or are we running
>> sphinx on the disc?
>>      
Sphinx creates static html, which is run on the disc. (we can 
potentially uninstal sphinx later to we really need the space).

> AFAIU we are running sphinx on the disc. It's pretty light-
> weight anyway, I see no reason not to. (I've just added the
> package download to install_main_docs.sh)
>
> just do:
>
> cd doc/overview/
> make html
> firefox ./_build/html/
>
> and pick one. then use prev,next in the top.
>
> same for doc/quickstart/
>
>
> honestly, it looks like a million bucks.
>
>
>    
>> What's the status (I see Hamish madly working away) of the
>> transition?
>>      
> well, I just figured out I'm maintaining 40% of the install
> scripts... help... please... not sustainable...
>
> actually converting html to reST is fairly easy, it just takes
> a few minutes, but I don't have sphinx on the machine I'm
> developing on so it's a rather inefficient and ugly back and
> forth of svn commits while I figure out how to use it and
> debug.
>
>    
>> I assume using the banner/css I made for live.osgeo.org is the
>> way to go for style?
>>      
>    
Yes your styles would be fine, although I'd like to work out how to move 
these styles into the rst/sphinx scripts.
> no idea.  check out the sphinx pages and re-evaluate.
>
>
> Hamish
>
> ps - added little osgeo graphics to the osgeo project overview
> pages for those projects that it is relevant for. Maybe set the
> width: a bit more so they aren't so bunched up next to the main
> project logo?  I think it is a good way to highlight the
> osgeo member projects while not doing so at the expense of
> others FOSS4Gs who happen to have their own Foundation already.
> Our enemy is obscurity in the face of the million dollar
> advertising budgets of our megacorp competitors, not each other.
> wasn't sure if the qgis-mapserver people wanted one or not,
> I leave it to them..
>
>
>
> _______________________________________________
> 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 Director
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