[CPS-devel] Building documentation for CPS products

[M.-A. DARCHE]

Dave Kuhlman a écrit :
> 
> I was able to reproduce this error by installing Docutils 0.3.9.
>

FYI the version installed on my system is 0.3.7.


> I've been using a version checked out from SVN, in which this
> problem seems to have been fixed.  I've made a patch to my script
> that is a work-around.  A diff/patch is below.  By the way, the
> snapshot currently at the Docutils Web site also fixes this:
> 
>     http://docutils.sourceforge.net/
>     http://docutils.sourceforge.net/docutils-snapshot.tgz
> 
> At that Web site, the snapshot is recommended over version 0.3.9.
> 
> Regardless, the patch is simple.  Here it is:
> 
>     --- buildCPSdocs-old.py 2006-01-05 09:11:01.000000000 -0800
>     +++ buildCPSdocs.py     2006-01-05 09:09:34.000000000 -0800
>     @@ -145,6 +145,7 @@
>                      settings_overrides = {
>                          'generator': 1,
>                          'stylesheet_path': stylesheetPath,
>     +                    'stylesheet': None,
>                          'source_url': baseName,
>                          }
>                      publish_file(source_path='%s' % sourceName,
> 
> 
> Please let me know whether this fixes the problem for you.
> 

With the diff you give the processing goes further but dies with the
following error:

[...]

Processing directory: ./CPSWorkflow/doc

Processing directory: ./CalCore/doc


##
## Building index files
##
Generating index file: index.txt
     File: index.txt --> index.html
Traceback (most recent call last):
   File "doc_tools/buildCPSdocs.py", line 643, in ?
     main()
   File "doc_tools/buildCPSdocs.py", line 627, in main
     options.force, options.quiet)
   File "doc_tools/buildCPSdocs.py", line 340, in generate_html_index
     settings_overrides=settings_overrides)
   File "/usr/lib/site-python/docutils/core.py", line 335, in publish_file
     enable_exit_status=enable_exit_status)
   File "/usr/lib/site-python/docutils/core.py", line 513, in 
publish_programmatically
     output = pub.publish(enable_exit_status=enable_exit_status)
   File "/usr/lib/site-python/docutils/core.py", line 196, in publish
     output = self.writer.write(document, self.destination)
   File "/usr/lib/site-python/docutils/writers/__init__.py", line 72, in 
write
     self.translate()
   File "/usr/lib/site-python/docutils/writers/html4css1.py", line 102, 
in translate
     visitor = self.translator_class(self.document)
   File "/usr/lib/site-python/docutils/writers/html4css1.py", line 200, 
in __init__
     stylesheet = utils.get_stylesheet_reference(settings)
   File "/usr/lib/site-python/docutils/utils.py", line 458, in 
get_stylesheet_reference
     assert not settings.stylesheet, \
AssertionError: stylesheet and stylesheet_path are mutually exclusive.


Please also note that PluggableUserFolder will not be part of CPS 3.4.x
and thus should be removed from doc_tools/doc_directories.xml.
But anyway the script should not die if a specified directory does not
exist. A warning should be printed.

Let me know if I should give you more details or if I'm doing something
wrong.

-- 
Marc-Aurèle DARCHE
NUXEO (Paris, France)                     http://nuxeo.com/
Nuxeo Collaborative Portal Server (CPS)   http://www.cps-project.org/
Gestion de contenu web / portail collaboratif / logiciel libre