2012/9/17 Jody Garnett <[email protected]>: > 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 > _______________________________________________ User-friendly Desktop Internet GIS (uDig) http://udig.refractions.net http://lists.refractions.net/mailman/listinfo/udig-devel
