Re: [udig-devel] walkthrough 1 updated to sphinx

[Frank Gasdorf <fgdrf@xxxxxxxxxxxxxxxxxxxxx>]

2012/6/13 Jody Garnett <jody.garnett@xxxxxxxxx>
>
> Great! Are you still working on the transformation from odt to rst?
>
> I have completed walkthrough 1. And updated the content.

I also updated the content a bit, more details down below ..

> Is the user doc conversion completed that we can start working on the content?
>
> I would like a review of the user doc conversion; we may wish to tweak things a bit before calling it done and working on the content.
>

I guess you are talking about the conversion from confluence. I would
prefer to have file names without blanks, I had a look into the docs
and I'm wondering about missing images (e.g.
user/en/html/Intersect%20Operation.html |image0|, |image1| and
|image3|). Some links are broken (user/en/html/Walkthrough%201.html)
and as a result you get around 800 Warnings from the sphinx build.
Therefor I remove the "turn warnings into error" option "-W".

IMHO we have some pages with identical content, we should got through
the pages and identify these to clean up. For example : we could move
the "Walkthrough 1" and "Walkthrough 2" pages into getting_started and
remove the getting_started/index page instead. In addition the
converted user documents are not listed in any toctree ...

>
> Today I worked on styling (removed background image) and fixed links in the top navigation div.
>
> I had a look at the origin odt file and the converted rst's a here some comments:
> - the images are references with pattern |image_name_extension|. I'm not sure about the current committed rst files but I expected a result like this from the the BulkConvert class :
> .. image::image/import_wiz.png
>
> I was going to ask you about that; should I generate the following instead:
>
> .. image:: /image/import_wiz.png
>
> (This would allow us to group the "tasks pages" into a task folder, since the "/image/import_wizard.png" would refer to the root directory conf.py is defined)
>
> The other more exciting option is to have it generate something like:
>
> .. image:: /../../../plugins/net.refractions.udig.catalog.ui/wizban/import_wiz.png

This solution has seductive charm but I'm not sure about how much
content we can recycle from the plugins folder. Hmm, some Icons for
sure but a lot of pictures in user/dev docs are screenshots from a
running application with menus and content. For now, let the images
where they are, in case of translations in the future we can move to
an other structure (like osgeo live) where all the images are in the
root folder.
I haven't checked it out, but please correct my if I'm wrong: the
images from walkthrough 1 are walkthrough 1 specific - same with
walkthrough 2. Therefor the images are at the right place I think.

> (This would pull the same image into the docs as is currently sued for the application)
>
> Let me know if you think either of these ideas is worth experimenting and running the conversion again.
>
> - I tested a bit with sidebars and have a solution for the notes within the odt files (I assume these were not converted by the odt2sphinx tool and we have to check ist after conversion):
>
> You assumption is correct; this was something I did manually after conversion.
>
>    - I added an additional line in layout.html of the udig theme : {%- block sidebar2 %}{% endblock %}
>    - I tested the ..sidebar:: directive in the ImportDirectlytoTheCatalog.rst file
>    - we can think about using ..notes:: directives instead but this would create longer pages than with the sidebar.
>
> I am not really worried about page length on a web page - so if "notes" is better just let me know.

Last night I pushed sidebars to master but I have no strong opinion
about notes vs. sidebars. The advantage of notes/warnings is that they
can have different styles. Sidebars makes some when creating pdfs with
rst2pdf.
Let's use notes and warnings for the moment.

> Question: For the GeoServer Install workbook I combined everything into a single page - should I do this for walkthrough 1?

Hmm, even no strong opinion about this. It might be a good idea to
have separated (html) pages because of printing a single chapter,
otherwise a browser have no chance to give you a "page from to" range.
Separate is fine.
>
> - I thought about using the rst2pdf extension to export pdf out of it but it failed to install it with sudo easy_install rst2pdf. I guess its because of my python env (2.5.1) and a missing dependencies .. Do you know how to update python on mac osx (lion)?
>
> Please use "home brew" to install python, and PIL and sphinx-build and so on. It is much easier.

Oh, had a looooong sleepless night because of this. I used mac port
and got several compile errors at the end during rst2pdf installation.
Tried it with python26 and python27 but it failed.. :( Strange, on
Windows I haven't had this problem ;)

> Have a look at the changes https://github.com/uDig/udig-platform/commit/4ad31494d2698d1e09ceb1e11176d2a5a53ad1fb
>
> looks good; don't you like how getting CSS to function is so much work; and then so very few lines of code in a diff.

Agree, I'm not a pro in CSS at all therefore its quite hard to get its
looking like expected. I'm working with SRWare Iron (Chrome) and use
the Expect elements functionality to change styles and html elements
until it fits my and copy the style configuration into the udig.css
files. But it burns so much time ....

>
> So … how to we push this to udig.github.com? I would like make a blog post once we have anything ready for to show.

Copy and Paste, commit and push ;) we shouldn't do this daily or in a
CI build. in my opinion if we release uDig we should update
udig.github.com as well.

> Jody

Tonight I've not the chance to work on docs because of the EM2012
Soccer Highlight Netherlands vs. Germany ;)

Frank