GNOME.org
 

[glom] Improved use of sphinx.

commit 6996b2602b4f917646fdd086f82847286a8b3c64
Author: Murray Cumming <murrayc murrayc com>
Date:   Mon Apr 19 15:06:31 2010 +0200

    Improved use of sphinx.
    
    	* configure.ac: AC_SUBST() GLOM_ABI_VERSION_UNDERLINED so we can use it
        in docs/pyglom_reference/Makefile.am. Mention these files that will be
        genereated form .in files with the ABI and version numbers substituted.
        Check for sphinx-build, though this should only matter when building docs.
    	* docs/pyglom_reference/conf.py.in:
    	* docs/pyglom_reference/index.rst.in: Use ABI and version variables instead
        of hard-coding. Add short introductory text with links.

 ChangeLog                                          |   42 +++++++++++++-------
 configure.ac                                       |    9 ++++-
 docs/pyglom_reference/Makefile.am                  |    9 ++--
 .../{sphinx_sources/conf.py => conf.py.in}         |   16 ++++----
 docs/pyglom_reference/index.rst.in                 |   23 +++++++++++
 docs/pyglom_reference/sphinx_sources/api.rst       |   23 -----------
 docs/pyglom_reference/sphinx_sources/index.rst     |   22 ----------
 7 files changed, 70 insertions(+), 74 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index a53d8f8..2981baf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2010-04-19  Murray Cumming  <murrayc murrayc com>
+
+    Improved use of sphinx.
+
+	* configure.ac: AC_SUBST() GLOM_ABI_VERSION_UNDERLINED so we can use it
+    in docs/pyglom_reference/Makefile.am. Mention these files that will be
+    genereated form .in files with the ABI and version numbers substituted.
+    Check for sphinx-build, though this should only matter when building docs.
+	* docs/pyglom_reference/conf.py.in:
+	* docs/pyglom_reference/index.rst.in: Use ABI and version variables instead
+    of hard-coding. Add short introductory text with links.
+
 2010-04-16  Murray Cumming  <murrayc murrayc com>
 
     Try to use sphinx for pyglom API documentation.
@@ -5,17 +17,17 @@
     * docs/pyglom_reference/Makefile.an:
 	* docs/pyglom_reference/sphinx_sources/:
     An attempt to use sphinx instead of pydoc. sphinx is used by Python itself.
-    I need to change my Python setup (not have Python in jhbuild) to test 
-    this properly, because I can't easily build pydoctor in my separate prefix. 
+    I need to change my Python setup (not have Python in jhbuild) to test
+    this properly, because I can't easily build pydoctor in my separate prefix.
 
 2010-04-16  Murray Cumming  <murrayc murrayc com>
 
 	Python: Really show warnings when modules can't be imported.
-	
-	* glom/python_embed/glom_python.cc: Add and use import_module() to make sure 
-	that we catch exceptions from boost::python::import(), so show the intended 
+
+	* glom/python_embed/glom_python.cc: Add and use import_module() to make sure
+	that we catch exceptions from boost::python::import(), so show the intended
 	warnings instead of just crashing with an uncaught exception.
-	Also correct the checks for empty/none boost::python::objects for imported 
+	Also correct the checks for empty/none boost::python::objects for imported
 	modules. A simple ! is not what it seems.
 
 2010-04-16  Murray Cumming  <murrayc murrayc com>
@@ -25,19 +37,19 @@
     * configure.ac: Use mm-common, removing macros/dk-warn.m4.
 	* docs/libglom_reference/Doxyfile.in:
 	* docs/libglom_reference/doxygen_to_devhelp.xsl:
-	* docs/libglom_reference/Makefile.am: Generate libglom documentation 
+	* docs/libglom_reference/Makefile.am: Generate libglom documentation
     properly usign build stuff copied from gtkmm.
-	* docs/pyglom_reference/Makefile.am: A silly little initial attempt to 
+	* docs/pyglom_reference/Makefile.am: A silly little initial attempt to
     have generated html for the glom python module, using pydoc.
 
 2010-04-15  Murray Cumming  <murrayc murrayc com>
 
   Python field calculation: Fix a crash.
-  
-	* glom/libglom/python_embed/pygdavalue_conversions.cc: 
-	glom_pygda_value_as_boost_pyobject(): Add a PyDateTimeAPI call, as already 
-	done in glom_pygda_value_from_pyobject(), to prevent a crash (and valgrind 
-	warning about 0 dereference) when using this (silly, wrong) field calculation, 
+
+	* glom/libglom/python_embed/pygdavalue_conversions.cc:
+	glom_pygda_value_as_boost_pyobject(): Add a PyDateTimeAPI call, as already
+	done in glom_pygda_value_from_pyobject(), to prevent a crash (and valgrind
+	warning about 0 dereference) when using this (silly, wrong) field calculation,
 	though I can't reproduce it in a unit test:
 	import datetime
   return (datetime.date.today() - record["date_of_birth"]).days / 365
@@ -45,8 +57,8 @@
 2010-04-15  Murray Cumming  <murrayc murrayc com>
 
   Python module: Improve API documentation.
-  
-	* glom/python_embed/python_module/py_glom_module.cc: Added some options and 
+
+	* glom/python_embed/python_module/py_glom_module.cc: Added some options and
 	text for docstrings, to improve the pydoc -w output.
 
 1.14.0:
diff --git a/configure.ac b/configure.ac
index e690bcc..7b7f5f7 100644
--- a/configure.ac
+++ b/configure.ac
@@ -44,8 +44,10 @@ AC_PROG_LIBTOOL
 AC_SUBST([GLOM_ABI_VERSION], [1.14])
 AC_DEFINE_UNQUOTED([GLOM_ABI_VERSION], ["$GLOM_ABI_VERSION"],
 		   [Define to the Glom ABI version string.])
+
 # Python modules can't be called glom-1.x, so we use underlines.
-AC_DEFINE_UNQUOTED([GLOM_ABI_VERSION_UNDERLINED], "AS_TR_SH([$GLOM_ABI_VERSION])",
+AC_SUBST([GLOM_ABI_VERSION_UNDERLINED], ["AS_TR_SH([$GLOM_ABI_VERSION])"])
+AC_DEFINE_UNQUOTED([GLOM_ABI_VERSION_UNDERLINED], ["$GLOM_ABI_VERSION"],
                    [Define to the Glom ABI version with '.' replaced by '_'.])
 
 # Only check for libgettextpo on non-Maemo platforms.
@@ -257,6 +259,9 @@ MM_ARG_WITH_TAGFILE_DOC([glibmm-2.4.tag], [glibmm-2.4])
 MM_ARG_WITH_TAGFILE_DOC([cairomm-1.0.tag], [cairomm-1.0])
 MM_ARG_WITH_TAGFILE_DOC([pangomm-1.4.tag], [pangomm-1.4])
 
+AC_CHECK_PROG([SPHINX_BUILD], [sphinx-build])
+AC_SUBST([SPHINX_BUILD])
+
 AC_CONFIG_FILES([Makefile
                  docs/user-guide/Makefile
                  po/Makefile.in
@@ -265,5 +270,7 @@ AC_CONFIG_FILES([Makefile
                  docs/libglom_reference/Makefile
                  docs/libglom_reference/Doxyfile
                  docs/pyglom_reference/Makefile
+                 docs/pyglom_reference/conf.py
+                 docs/pyglom_reference/index.rst
                  win32/glom.iss])
 AC_OUTPUT
diff --git a/docs/pyglom_reference/Makefile.am b/docs/pyglom_reference/Makefile.am
index 9f691da..a7315fc 100644
--- a/docs/pyglom_reference/Makefile.am
+++ b/docs/pyglom_reference/Makefile.am
@@ -1,4 +1,4 @@
-# pydoc can write docs for all modules in a directory (or a module name), 
+# pydoc can write docs for all modules in a directory (or a module name),
 # but doesn't like being given a path to any actual file.
 
 
@@ -8,9 +8,8 @@
 #	mkdir html
 #	mv glom_1_14.html html/index.html
 
-ALLSPHINXOPTS   = -d _build/doctrees sphinx_sources
-
 html:
-	sphinx-build -b html $(ALLSPHINXOPTS) html
+	rm -rf html
+	sphinx-build -b html ./ html/
 
-MAINTAINERCLEANFILES = html/*
+MAINTAINERCLEANFILES = html/* outdir
diff --git a/docs/pyglom_reference/sphinx_sources/conf.py b/docs/pyglom_reference/conf.py.in
similarity index 93%
rename from docs/pyglom_reference/sphinx_sources/conf.py
rename to docs/pyglom_reference/conf.py.in
index e7430bd..eab82d6 100644
--- a/docs/pyglom_reference/sphinx_sources/conf.py
+++ b/docs/pyglom_reference/conf.py.in
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# glom_1_14 documentation build configuration file, created by
+# glom_ GLOM_ABI_VERSION_UNDERLINED@ documentation build configuration file, created by
 # sphinx-quickstart on Fri Apr 16 16:21:26 2010.
 #
 # This file is execfile()d with the current directory set to its containing dir.
@@ -37,7 +37,7 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'glom_1_14'
+project = u'glom_ GLOM_ABI_VERSION@'
 copyright = u'2010, Murray Cumming'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -45,9 +45,9 @@ copyright = u'2010, Murray Cumming'
 # built documents.
 #
 # The short X.Y version.
-version = '1.14.0'
+version = '@PACKAGE_VERSION@'
 # The full version, including alpha/beta/rc tags.
-release = '1.14.0'
+release = '@PACKAGE_VERSION@'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -147,7 +147,7 @@ html_theme = 'default'
 #html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
@@ -158,7 +158,7 @@ html_theme = 'default'
 #html_file_suffix = ''
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'glom_1_14doc'
+htmlhelp_basename = 'glom_ GLOM_ABI_VERSION_UNDERLINED@doc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -172,8 +172,8 @@ htmlhelp_basename = 'glom_1_14doc'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'glom_1_14.tex', u'glom\\_1\\_14 Documentation',
-   u'Murray Cumming', 'manual'),
+  ('index', 'glom_ GLOM_ABI_VERSION_UNDERLINED@.tex', u'glom\\_1\\_ GLOM_ABI_VERSION@ Documentation',
+   u'Openismus GmbH', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
diff --git a/docs/pyglom_reference/index.rst.in b/docs/pyglom_reference/index.rst.in
new file mode 100644
index 0000000..178a0da
--- /dev/null
+++ b/docs/pyglom_reference/index.rst.in
@@ -0,0 +1,23 @@
+.. glom_1_14 documentation master file, created by
+   sphinx-quickstart on Fri Apr 16 16:21:26 2010.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Glom Python Documentation
+=====================================
+
+This API may be used in Glom field calculations or button scripts. Field
+calculations have a :class:`glom_ GLOM_ABI_VERSION_UNDERLINED@.Record` parameter. Button scripts have a
+:class:`glom_ GLOM_ABI_VERSION_UNDERLINED@.Record` parameter and a :class:`glom_ GLOM_ABI_VERSION_UNDERLINED@.UI` parameter.
+
+.. toctree::
+   :maxdepth: 3
+
+.. automodule:: glom_ GLOM_ABI_VERSION_UNDERLINED@
+   :members:
+   :undoc-members:
+
+Indices and tables
+==================
+
+* :ref:`search`
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]