2.1 documentation

[cvvergara]

Based on the document: https://docs.google.com/document/d/1lgBNr9I-otJmMJMeYyRTxi51VxvX9b6yaRWBT2p_ip4/edit

I am modifying documentation for 2.1: So far this has being modified. So far this have being modified.

http://imaptools.com:8080/docs/pgr2.1-doc/doc/src/developer/index.html http://imaptools.com:8080/docs/pgr2.1-doc/doc/src/developer/sampledata.html#sampledata http://imaptools.com:8080/docs/pgr2.1-doc/src/dijkstra/doc/index.html#pgr-dijkstra http://imaptools.com:8080/docs/pgr2.1-doc/src/driving_distance/doc/index.html#pgr-driving-distance

I need reviewer's.

Please post your comments in this issue.

[cvvergara]

Suggestion: sum_cost instead of tot_cost

[boerngen-schmidt]

@cvvergara I do not know if it was the right way to do it, but in general there are some weird abbreviations in the function signatures and results.

For example: tot_cost -> total_cost or sum_cost

[cvvergara]

@boerngen-schmidt yes, I noticed (lazy of my part of not finishing words), and posted the suggestions in the document, lets see what do other users vote for: total_cost or sum_cost

[cvvergara]

@boerngen-schmidt From #349 which is devoted to Astar, but has general issues about documentation

Right now my focus is on the documentation of the new signatures; I made the proposal, I've been making the code, I have to make it work for linux, windows, and mac, I've been testing, I am making the documentation of the new signatures. So for this release The other function's documentation, for the 2.1 will remain the same, that is, with the bugs/issues etc not solved.

Yes, I agree that a section that: "broad explanation of the algorithms in general, like pros and cons, as well as how they work. " is to be useful, but I cant do it all by myself.

I was supposed to deliver this V2.1 by today, Friday July 6th, and its not going to happen and next week I am out of the city.

If you can help me with the documentation, it would be great!!! Pull requests are always welcome.

[cvvergara]

@robe2 Regina, I need someone to check the changes in the documentation I'm doing. I know you are writing a book about pgRouting, I was wondering if you could have some time (after your postGIS installation) to check the documentation. For the moment I think I am done documenting pgr_dijkstra. Because we are still using the 2.x version then the old signatures remain, and I just make minor changes on the old documentation: https://github.com/pgRouting/pgrouting/blob/develop_2_1_0/src/dijkstra/doc/dijkstra_v2.rst this is for the new signatures: https://github.com/pgRouting/pgrouting/blob/develop_2_1_0/src/dijkstra/doc/dijkstra_v3.rst Of course it looks nicer if you generate the documentation locally in your computer. (and by the way, can you add develop_2_1_0 of the main repository to winnie test? ) thanks Vicky

[robe2]

Sure will check and also add develop_2_1_0 to winnie

[robe2]

I setup 2_1_0 branch on winnie

http://winnie.postgis.net:1500/view/pgRouting/job/pgRouting_matrix_branch_develop_2_1_0/

Can't figure out why it's showing success though. I presume you haven't ported all your changes to that version yet since it still has the old errors I saw before.

[cvvergara]

I did add the changes, but I merged to add vrppdtw, I need to fix the cmake to include that one. The tester might not be throwing the correct failure when things go wrong when creating the extension.

[cvvergara]

Adding a BUG because some links are broken here: http://docs.pgrouting.org/v2.1.0-alpha/doc/src/recipes/index.html#recipes

[cvvergara]

Hopefully all links are ok.

[cvvergara]

This comment in #368 made me to think that:

• the vrp functions are to be moved to the recipes section in the documentation, as they were not part of V2.0.0 or
• instead of experimenal functions name the section as "proposed functions" and move the convinience functions to the "proposed functions" to keep them visible to the general public.

[woodbri]

V2.1 does allow for new functions to be added, the only constraint is that we should not break any officially supported function from V2.0. The PSC usually makes these decisions.

[cvvergara]

I had to ask what PSC means, "Participate, Suggest and Comment" was the first idea that came to mind. As the first time I see the term, can I ask who are they?

[woodbri]

http://pgrouting.org/development.html (see last Section) and http://pgrouting.org/rfc/rfc-01.html

While I am the only remaining PSC member that has been active in the past 2-4 years, I have been making decisions based on feedback and consensus from Daniel and Vicky when I did 2.0. Since the three of us have been the most active contributing members of the team I see no reason not to continue with the three of us until we get some additional contributing members.

Regarding the release, you have taken on the role of release manager so unless so run with that.

[cvvergara]

@woodbri @dkastl @robe2 Can you see if this index structure of the documentation is better http://docs.pgrouting.org/v2.1.0-alpha2/doc/index.html

[dkastl]

I think we need a better name for pgr_brokenGraph.

[cvvergara]

Ok, I will put Zia- vote, and also add that the name is not the final name, that can be changed. I need to change code for that also. I'll post again as soon I get that done.

[cvvergara]

Modified the documentation now its pgr_labelGraph http://docs.pgrouting.org/v2.1.0-alpha2/doc/index.html#proposed-functions-proposed-by-zia-mohammed http://docs.pgrouting.org/v2.1.0-alpha2/src/label_graph/doc/analyze_brokengraph.html#pgr-labelgraph

[robe2]

Looking at pgr_flipEdges http://docs.pgrouting.org/v2.1.0-alpha2/src/common/doc/convenience/flip_edges.html

It seems to me the best use of this function would be to reverse edges in an edges table or create a new edges table from an existing edges table. However the documentation doesn't explain that. Am I wrong in assuming that would be the primary use case?

Also I think maybe pgr_reverseEdges might be a slightly better name since the function builds on PostGIS ST_Reverse function. pgr_flipEdges sounds too much like PostGIS ST_FlipCoordinates which has a totally different meaning.

[woodbri]

No, the purpose of this function is to conditionally flip/reverse and edge in a path. When you get the results of pgr_dijkstra() or whatever , you get a list of edges that represents the path, but the edges are in the direction of digitization and not in the direction of the path. So each edge is evaluated as to whether it is moving along the path or counter to the path. If the edge is counter to the path then it gets flipped/reversed. So when you are done all the edges are directed in the flow of the path.

The documentation probably needs to be updated to reflect this.

[robe2]

Okay got it. Guess that is what was meant by "results of a route"

Would probably help to add like results of output of pg_dijikstra and other routing functions and the see Also should point to those.

[robe2]

Why does this function have 3.0 on it?

http://docs.pgrouting.org/v2.1.0-alpha/src/dijkstra/doc/dijkstra_v3.html#pgr-dijkstra-v3

The new signature is nicer than the old (I like the output better since the columns you don't have to reconcile to figure out what id1,id2 mean) and also not having to pass in has_rcost. However if people are expected to use this, it should not have a 3.0 number on it.

[cvvergara]

@robe2 I followed your suggestion: http://docs.pgrouting.org/v2.1.0-alpha2/src/dijkstra/doc/index.html#pgr-dijkstra @sanak The new documentation: http://docs.pgrouting.org/v2.1.0-alpha2/src/driving_distance/doc/dd_alphashape.html#pgr-alphashape http://docs.pgrouting.org/v2.1.0-alpha2/src/driving_distance/doc/dd_points_as_polygon.html#pgr-points-as-polygon

[sanak]

@cvvergara The pgr_alphaShape and pgr_pointsAsPolygon documents are still old ones. I guess that some more settings may be necessary.

[cvvergara]

I'll review the merge again.

[cvvergara]

@sanak I forgot to push gh-pages, sorry can you check again?

[sanak]

@cvvergara Okay, I confirmed those. Thanks!

But sorry, I missed 2 pgr_alphashape (not S, but s) in the "Name" and "Synopsis" sections. Can I update those to pgr_alphaShape directly (from Github edit UI) on develop_2_1_0 branch ? Or is it better for me to update develop_2_1_0_issue383 branch again ?

[cvvergara]

@sanak you can do directly. I am not modifying anything now, just tell when you are done so I update gh-pages.

[sanak]

@cvvergara Okay, thanks for confirmation. I just updated develop_2_1_0 branch directly. Difference: https://github.com/pgRouting/pgrouting/commit/f3e252cb48e93b01818ddb82d00f1eca8c697170

[cvvergara]

@sanak Here is for your review. http://docs.pgrouting.org/v2.1.0-alpha2/src/driving_distance/doc/dd_alphashape.html

[cvvergara]

I am not making changes to the documentation so I will close it. Can be reopened in case of emergency.