[pgrouting-dev] Build documentation with Sphinx added

[Daniel Kastl]

Hi Steve,

I added Sphinx generated documentation to the CMake build as an option:

cmake -H. -Bmybuild -DWITH_TSP=ON -DWITH_DD=ON
 cd mybuild && make

Obviously this requires to have Sphinx installed.
Right now it contains only your README.rst file that I found in the doc
folder, but the build works.

A few questions/comments:

(1) Where should "make" install the "html" folder?
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".
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.
Kishore added "make distclean", which wouldn't be needed anymore in this
case, which safes again some lines of CMake code.

(2) I found a nice CMake example for Sphinx. It keeps all the Sphinx
related stuff within doc/CMakeLists.txt
All I had to addto CMakeLists.txt in the root directory was 4 lines to
support  "-DWITH_DOC=ON".
I think it would be a good idea to also move algorithm related
configuration to core/CMakeLists.txt if possible.

(3) Maybe silly, but is "doc" a common directory name or would "docs" be
better?

(4) In your README.rst you added a header including the following two lines:

:Date: $Date: 2013-03-17 10:07:00 -0500 (Sun, 17 Mar 2013) $
 :Revision: $Revision: 0000 $

How would you keep this updated?
I remove this and put the Git hash tag with a link to Github somewhere for
the whole document.
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?

(5) You mentioned that we could try to generate documentation from comments
within source files.
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.
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.

Daniel


-- 
Georepublic UG & Georepublic Japan
eMail: daniel.kastl at georepublic.de
Web: http://georepublic.de
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/pgrouting-dev/attachments/20130324/393dc36b/attachment.html>