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@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@maps:~/work/pgrouting$ rm CMakeCache.txt
woodbri@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: 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