Hi Steve,<div><br></div><div>I added Sphinx generated documentation to the CMake build as an option:</div><div><br></div><div><div><span class="Apple-tab-span" style="white-space:pre">  </span>cmake -H. -Bmybuild -DWITH_TSP=ON -DWITH_DD=ON </div>

<div><span class="Apple-tab-span" style="white-space:pre">      </span>cd mybuild && make</div></div><div><br></div><div>Obviously this requires to have Sphinx installed.</div><div>Right now it contains only your README.rst file that I found in the doc folder, but the build works.</div>

<div><br></div><div>A few questions/comments:</div><div><br></div><div>(1) Where should "make" install the "html" folder?<br>I'm not sure anymore we need to keep the "lib" directory. For "html" it looks a bit weird and nobody would search in a directory named "lib".<br>

I think it would be better to use a "build" directory for everything before "make install". When deleting this directory all CMake and Sphinx generated files would be deleted as well.<br>Kishore added "make distclean", which wouldn't be needed anymore in this case, which safes again some lines of CMake code.</div>

<div><br></div><div>(2) I found a nice CMake example for Sphinx. It keeps all the Sphinx related stuff within doc/CMakeLists.txt</div><div>All I had to addto CMakeLists.txt in the root directory was 4 lines to support  "-DWITH_DOC=ON".</div>

<div>I think it would be a good idea to also move algorithm related configuration to core/CMakeLists.txt if possible.</div><div><br></div><div>(3) Maybe silly, but is "doc" a common directory name or would "docs" be better?<br>

<div><br></div></div><div>(4) In your README.rst you added a header including the following two lines:</div><div><br></div><div><div><span class="Apple-tab-span" style="white-space:pre">  </span>:Date: $Date: 2013-03-17 10:07:00 -0500 (Sun, 17 Mar 2013) $</div>

<div><span class="Apple-tab-span" style="white-space:pre">      </span>:Revision: $Revision: 0000 $</div></div><div><br></div><div>How would you keep this updated?</div><div>I remove this and put the Git hash tag with a link to Github somewhere for the whole document.</div>

<div>Then someone can look-up in the Github history if really needed. By having the documentation together with the source code, every tag/release should also include the documentation version anyway, right?</div><div><br>

</div><div>(5) You mentioned that we could try to generate documentation from comments within source files.</div><div>I would prefer to write the documentation separately for several reasons: It's my goal to make the documentation easy to read and understand. Better to forget some helper functions that nobody every needs and concentrate on the important ones with good examples. Also writing documentation within comments is a bit painful (no code highlighting) and parsing it without errors might be too much work for just a small library.</div>

<div>Instead I would say that documentation in source files should contain the information a pgRouting developer needs to know, and the documentation build with Sphinx should be for pgRouting users.</div><div><br></div><div>

Daniel</div><div><br clear="all"><div><br></div>-- <br><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse">Georepublic UG & Georepublic Japan<br>eMail: <a href="mailto:daniel.kastl@georepublic.de" style="color:rgb(66,99,171)" target="_blank">daniel.kastl@georepublic.de</a><br>

Web: <a href="http://georepublic.de/" style="color:rgb(66,99,171)" target="_blank">http://georepublic.de</a></span>
</div>