[pgrouting-dev] Documentation review comments

[Stephen Woodbridge]

On 5/26/2013 12:58 PM, Daniel Kastl wrote:
>
>
>
> On Mon, May 27, 2013 at 12:18 AM, Stephen Woodbridge
> <woodbri at swoodbridge.com <mailto:woodbri at swoodbridge.com>> wrote:
>
>     Hi Daniel,
>
>     You are doing an awesome job with the documentation. I have a few
>     minor comments on things I have noticed while review it.
>
>     * Can we break out the "Utility functions" to a separate page that
>     gets indexed to make it easier to find. It is currently at the
>     bottom of the pgrouting_analytics page.
>
>
> I didn't look at this much yet, but I thought there should be 1 page for
> each function.
> Then if these functions should be explained in context, grouped together
> however, then I would add a chapter to "Tutorials" for example.
>
> So if there is no single page yet for some functions, then it'S just not
> done yet.

OK, that will be cool. I like that design better.

>     * pgr_quote_ident seems to be on its own page, but this and the
>     utilities should be cross references may via the "See Also" links.
>
>
> Some "See Also" links were obvious, but I thought it's OK to do this at
> the end. Otherwise if a page name changes, we need to fix it again.

Sure, that makes perfect sense to me.

>     * I see references to "(built-in function)" but don't remember
>     seeing any description of what this means to the user or why we are
>     calling them out as such.
>
>
> I don't remember either ;-)
> Where did you find this?

I found them in the Index, they are appended to some of the function 
names under 'P'. BTW, the index seems to be a go place to view the names 
of functions and how they are organized.

>     * many of the built-in functions do not conform to our naming
>     convention. So may be we need to focus on updating these functions
>     and the functions that call these. Also I think the doc is just out
>     of date for many of these, because I seem to remember changing the
>     names on these.
>
>
> Could be. I'm usually looking at pgAdmin3 to get a list of all functions.
> Some I didn't touch, because I wasn't sure they would be removed or renamed.

OK, I was looking in the Index, so maybe comparing the pgAdmin list to 
the index list wi a good way to detect doc errors.

>     * I notice in the index that we have references "module", "[1]",
>     "[2]", "[3]", etc. I'm not sure the [n] is very useful and should
>     probably get changed to some text string that is more meaningful.
>     And common module, ... in index makes no sense to me. I'm not sure
>     how this all works in sphinx or if we can clean this up or not.
>
>
> "Module" is a feature that is done by Sphinx auto-magically when it's
> not turned off. And a "Module" is defined like here
>
> .. index::
>      single: pgr_kdijkstraCost(text,integer,integer[],boolean,boolean)
>      single: pgr_kdijkstraPath(text,integer,integer[],boolean,boolean)
>      module: kdijkstra
>
> I'm not su re really how useful this is for us. It just does the index
> records itself.
> And I don't know well how to configure it. We can easily turn it off if
> it's just confusing and enable it again when we know out to use it right.

Well, we might want to play with turning it off, and manually tagging 
what goes in the index, however that is done if it gives us better 
control. My concern is more about how the doc looks, but if there are 
simple tools in sphinx to decrease maintenance of the docs that is good 
also if we can get it to work for us.

At the moment you are master of sphinx ;)

Thanks,
   -Steve

> Daniel
>
>
>     Anyway, some ideas to make things a little nicer. I really like how
>     professional and consistent the docs look. Great job on these.
>
>     Thanks,
>        -Steve
>     _________________________________________________
>     pgrouting-dev mailing list
>     pgrouting-dev at lists.osgeo.org <mailto:pgrouting-dev at lists.osgeo.org>
>     http://lists.osgeo.org/__mailman/listinfo/pgrouting-dev
>     <http://lists.osgeo.org/mailman/listinfo/pgrouting-dev>
>
>
>
>
> --
> Georepublic UG & Georepublic Japan
> eMail: daniel.kastl at georepublic.de <mailto:daniel.kastl at georepublic.de>
> Web: http://georepublic.de <http://georepublic.de/>
>
>
> _______________________________________________
> pgrouting-dev mailing list
> pgrouting-dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/pgrouting-dev
>