[pgrouting-dev] Build documentation with Sphinx added

[Stephen Woodbridge]

Hi Daniel,

On 3/23/2013 1:26 PM, Daniel Kastl wrote:
> 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

This seems very awkward and I do not see -H and -B options in cmake 
version 2.8.10.2 documentation, but it seems to work almost.

It creates a local "mybuild/lib" dir and builds the *.so into that, but 
it still assembles pgrouting--1.0.7.sql.in, pgrouting--1.0.7.sql, and 
pgrouting.control into the top level "lib" dir.

I installed sphinx, how to I build the doc files and where do they get 
staged?

> 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.

Ok, this is a bunch of questions, let me try to organize it.

"lib" directory is really a staging area for the files that we build. I 
like this for a few of reasons. I don't care what the name is we could 
call it "staging"

* this allows you to do a make and see all the targets before they get 
installed, it is also cleaned out by make clean

* we could put "html" in this folder and have make or make install print 
a message that these need to be manually installed somewhere.

* we could also have make install place them in:
     /usr/share/pgrouting/<version>/html/
since we will be versioning pgrouting

* currently "build" contains  various tools which could get moved 
elsewhere in the future or could br renamed to "tools"

* I believe make distclean exists in my makefile and you need to keep it 
in case someone runs cmake in the source tree.

* also if I run cmake with an optional folder to build in in the source 
tree, I still have to manually remove it.

> (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.

This sounds good. We might want a target "-DWITH_DOC_ONLY=ON" which 
skips building the binaries.

So it does not look like you have you have the DOC integrated with cmake 
yet, or you did not push all the files required. clone it into a new 
clean directory and try it there or diff your working tree and the clean 
tree to see whats missing.

I added to the top level CMakeLists.txt file so it now supports 
"-DWITH_DOC=ON" but you didn't provide a"FindSphinx.cmake" file so:

woodbri at maps:~/work/pgrouting$ cmake -H. -Bmybuild -DWITH_TSP=ON 
-DWITH_DD=ON
-- POSTGRESQL_EXECUTABLE is /usr/lib/postgresql/8.4/bin/postgres
-- POSTGRESQL_PG_CONFIG is /usr/bin/pg_config
-- Found PostgreSQL: /usr/include/postgresql/8.4/server, /usr/lib
-- Boost version: 1.42.0
Boost headers were found here: /usr/include
POSTGRESQL_VERSION_STRING is PostgreSQL 8.4.16
POSTGRESQL_VERSION is 8.4.16
Install directory for libraries is set to /usr/lib/postgresql/8.4/lib
Install directory for SQL files is set to /usr/share/pgrouting
CMake Error at doc/CMakeLists.txt:6 (find_package):
   By not providing "FindSphinx.cmake" in CMAKE_MODULE_PATH this project has
   asked CMake to find a package configuration file provided by 
"Sphinx", but
   CMake did not find one.

   Could not find a package configuration file provided by "Sphinx" with any
   of the following names:

     SphinxConfig.cmake
     sphinx-config.cmake

   Add the installation prefix of "Sphinx" to CMAKE_PREFIX_PATH or set
   "Sphinx_DIR" to a directory containing one of the above files.  If 
"Sphinx"
   provides a separate development package or SDK, be sure it has been
   installed.


-- Configuring incomplete, errors occurred!

woodbri at maps:~/work/pgrouting$ rm CMakeCache.txt
woodbri at maps:~/work/pgrouting$ rm -rf mybuild/

I can look into this. I think we only need to call

   FIND_PROGRAM(SPHINX_EXE NAMES sphinx-build)

And check that we found it or throw and error.

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

Linux has /usr/share/doc/ Think of it like library (singular) where you 
store lots of books (plural). But I don't really care.

> (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?

Yeah, that is an old SVN-ism, I'm not sure what the git equivalent is. 
We might be able to do something like this with a .git/hooks/pre-commit 
for example `git rev-parse --verify HEAD` returns the object name (hash) 
of the current commit.

An other way to manage this is to scan all the files search for these 
patterns and replace the text as part of the build process. Sphinx might 
have a macro to do the data.

> I remove this and put the Git hash tag with a link to Github somewhere
> for the whole document.

How do we do this?

> 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?

Right, doc should be versioned to reflect the code.

> (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.

Yes, I agree with this. There is not reason that this can not use rst 
markup as well.

Thanks for the help,
   -Steve