On 5/26/2013 12:58 PM, Daniel Kastl wrote:
On Mon, May 27, 2013 at 12:18 AM, Stephen Woodbridge
<woodbri@swoodbridge.com <mailto:woodbri@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@lists.osgeo.org <mailto:pgrouting-dev@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@georepublic.de <mailto:daniel.kastl@georepublic.de>
Web: http://georepublic.de/>
_______________________________________________
pgrouting-dev mailing list
pgrouting-dev@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/pgrouting-dev