Re: [udig-devel] trying out sphinx template options

[Frank Gasdorf <fgdrf@xxxxxxxxxxxxxxxxxxxxx>]

2012/9/17 Jody Garnett <jody.garnett@xxxxxxxxx>:
> Afternoon Frank - did a bit of research into getting a global table of
> contents for the udig.github.com site …

Great, made some progress for udig doc deployment scripts as well. See
down below for details..

>
> Tried out the following "basic" (http://sphinx.pocoo.org/theming.html)
> built-in template in order to experiment with what sphinx does today.
>
> Pros:
> - get a global TOC but it is not very deep
> - control of what sidebar appears on what page (see example conf.py)
> - Search is very nicely done (can we get this to work on our website?)

IMHO it doesn't make sense to have toc
(http://sphinx.pocoo.org/templating.html?highlight=search#toc) for
every page because of the current structure of sides. Most of the
pages are just a single chapter with one H1 headline and some
headlines of h2. If we would merge pages using the include directive
(we had one : https://github.com/uDig/udig-platform/blob/c8f30255991eee00df6fab7a96b6f1f57077bb04/docs/user/en/getting_started/walkthrough2/walkthrough2.rst)
it would be a good thing to have a toc on this page (because its
pretty long).

I would prefer TOC directive
(http://sphinx.pocoo.org/templating.html?highlight=search#toc) to get
toc's into pages where it makes sense (longer pages like complete
quickstart or walkthrough documents)

pros :
* direct jump to selected header
* possibility to create other documents out of it (e.g. pdf's)

cons:
* page source would only show the structure if using includes,
otherwise if the chapters got merged into on rst-file
* the source of the page is pretty long (but hopefully homogeny over
chapters) and it's not easy to merge if more then one editor would
work on it. (But we all have experiences merging source files, haven't
we? ;)

> Cons:
> - The "sticky" sidebar works; but could not get the could not get the
> "collapsiblesidebar" to work

Do you mean the capability to "show and hide" the sidebar. In one of
the first sphinx conversion mails I mentioned cloudtheme
(http://packages.python.org/cloud_sptheme/cloud_theme.html), see
"collapsiblesidebar" configuration in the layout section
(http://packages.python.org/cloud_sptheme/cloud_theme.html#layout).

What do you think about building our theme on top of cloudtheme after
installing it with

       easy_install cloud_sptheme

?

IMO we should add search capability to our pages. It's absolutely
worth for the users/developers to hav this entry point available. I
guess we have to change the layout a bit to get the search filed in a
div element without having a toc on the left/right side.


Tested Depoyment to udig.refractions.net via webdav and maven-wagon-plugin:
- added build profile "depolydocs" that
- checks via antrun, whether it's a SNAPSHOT or a Release build, if
its a release deploy to stable folder structure, otherwise use latest
- requires a configuration in distributionManagement section of pom, e.g.

<distributionManagement>
    <repository>
      <id>refractions-webdav</id>
      <url>dav:http://udig.refractions.net/files/docs</url>
    </repository>
  </distributionManagement>

- requires server configuration in settings.xml with connection
settings (user, password) for the specified server


What problems I had:
- Its not possible to remove folders via wagon plugin -> otherwise use
maven anttask to
- I can't admin remote folders (at http://udig.refractions.net/files)
, who can give support for mac to remove already deployed (test)
folders)
- deployed user/developer docs contains strange chars (I guess coming
from upload file conversion),  see arrows in navigation header and
arrows in menuselection directives :
  - http://udig.refractions.net/files/docs/latest/user/uDig%20Overview.html

- do we have the chance to set up a shell script on refractions fedora
webserver and have we ssh access to the machine. Idea is to use a
script that extracts an uploaded zip and deploys the content to
configures structure (latest, stable and redirects stable to the
current release docs). If this would be possible we could reduce the
amount of uploaded data and would have much more control over the
deployment process than we would have with maven. Question: how does
geotools and geoserver deploy documentations (javadoc, userguide, etc)

Cheers, Frank

> Sad:
> - http://matplotlib.org/sampledoc/ tutorial is no longer available, the main
> website indicates the author of http://matplotlib.org/ has died
>
> --
> Jody Garnett
>