Merge lp:~thisfred/u1db/cdocs-improvements into lp:u1db

[Eric Casteleijn]

Added an introduction text to the mainpage, made html-docs build the cdocs, fixed make html-docs.

Added an introduction text to the mainpage, made html-docs build the cdocs, fixed make html-docs.

[Lucio Torre (lucio.torre)]

 +_doxygen/html/u1db_8h.html
 _build/html/index.html

both reference wont work when this is generated and moved to a production site.

review: Approve

[Eric Casteleijn (thisfred)]

> +_doxygen/html/u1db_8h.html
> _build/html/index.html
>
> both reference wont work when this is generated and moved to a production
> site.

Yeah, I tried but I couldn't seem to add a relative link in doxygen. I didn't realize the README is also turned into html. Since it's REST, I should be able to make links there.

[lp:~thisfred/u1db/cdocs-improvements]

441. By Eric Casteleijn on 2012-10-19

removed path

=== modified file 'CMakeLists.txt'
--- CMakeLists.txt	2012-09-07 17:25:57 +0000
+++ CMakeLists.txt	2012-10-19 14:54:22 +0000
@@ -44,7 +44,7 @@
     COMMAND cd html-docs && make doctest && cd ..
 )
 
-add_custom_target(check-nodoc
+add_custom_target(check-nodoctests
     COMMAND python -m testtools.run discover
     DEPENDS build-inplace-for-tests
 )
@@ -54,10 +54,6 @@
     DEPENDS build-inplace-for-tests doctests
 )
 
-add_custom_target(cdocs
-    COMMAND doxygen html-docs/doxygen.conf
-)
-
 add_custom_target(build-inplace-for-tests
     COMMAND U1DB_TEST=1 python setup.py build_ext -i -f -I ${CMAKE_SOURCE_DIR}/include
     DEPENDS ReplicatePythonSourceTree u1db
@@ -83,7 +79,7 @@
 )
 
 add_custom_target(html-docs
-    COMMAND cd ${CMAKE_SOURCE_DIR}/html-docs; make html
+    COMMAND cd ${CMAKE_SOURCE_DIR}/html-docs \; make html
 )
 
 SET(CPACK_GENERATOR "TGZ")

=== modified file 'README'
--- README	2012-10-04 12:29:11 +0000
+++ README	2012-10-19 14:54:22 +0000
@@ -50,6 +50,16 @@
 Building the docs
 =================
 
-cd html-docs
-make doctest # check that the code examples all still work
-make html # build HTML documentation at _build/html/index.html
+cmake . && make html-docs
+
+after which the reference implementation documentation can be found at::
+
+html-docs/_build/html/index.html
+
+and the C implementation documentation at::
+
+html-docs/_doxygen/html/index.html
+
+though a more useful starting point may be::
+
+_doxygen/html/u1db_8h.html

=== modified file 'html-docs/Makefile'
--- html-docs/Makefile	2011-12-21 11:09:04 +0000
+++ html-docs/Makefile	2012-10-19 14:54:22 +0000
@@ -36,7 +36,10 @@
 clean:
 	-rm -rf $(BUILDDIR)/*
 
-html: doctest
+cdocs: 
+	doxygen doxygen.conf
+
+html: doctest cdocs
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

=== modified file 'html-docs/doxygen.conf'
--- html-docs/doxygen.conf	2012-08-22 13:32:37 +0000
+++ html-docs/doxygen.conf	2012-10-19 14:54:22 +0000
@@ -38,7 +38,7 @@
 # for a project that appears at the top of each page and should give viewer
 # a quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          =
+PROJECT_BRIEF          = "U1DB: An API for synchronisable databases."
 
 # With the PROJECT_LOGO tag one can specify an logo or icon that is
 # included in the documentation. The maximum height of the logo should not
@@ -52,7 +52,7 @@
 # If a relative path is entered, it will be relative to the location
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = html-docs/_doxygen
+OUTPUT_DIRECTORY       = _doxygen
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
 # 4096 sub-directories (in 2 levels) under the output directory of each output
@@ -648,7 +648,7 @@
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = include/u1db/u1db.h src/u1db.c
+INPUT                  = ./intro.dox ../include/u1db/u1db.h ../src/u1db.c
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is

=== added file 'html-docs/intro.dox'
--- html-docs/intro.dox	1970-01-01 00:00:00 +0000
+++ html-docs/intro.dox	2012-10-19 14:54:22 +0000
@@ -0,0 +1,8 @@
+/*! \mainpage U1DB Index
+ *
+ * \section intro_sec Introduction
+ * This is the C implementation of the u1db protocol, with a SQLite backend.
+ * 
+ * If you're new to u1db, the documentation of the reference implementation is
+ * probably the best place to start, which can be found at _build/html/index.html
+*/

=== modified file 'include/u1db/u1db.h'
--- include/u1db/u1db.h	2012-10-09 17:00:12 +0000
+++ include/u1db/u1db.h	2012-10-19 14:54:22 +0000
@@ -18,6 +18,17 @@
  * @file u1db.h
  */
 
+/*! \mainpage U1DB Index Page
+ * 
+ * \section intro_sec Introduction
+ *
+ * This is the C implementation of the u1db protocol, with a SQLite backend.
+ *
+ * If you're new to u1db, the documentation of the reference implementation is
+ * probably the best place to start.
+ *
+*/
+
 #ifndef _U1DB_H_
 #define _U1DB_H_