[RFC][PATCH] Produce HTML docs to upload on server

[John Arbash Meinel]

Alexander Belchenko wrote:
> I do cross-platform rst2html launcher to use directly from Makefile.
> Therefore Makefile almost not changed.
> 
> To produce HTML docs to upload onto Canonical server use command:
> 
> make htmldocs
> 
> Produced docs will be placed to ./html_docs/ directory. This can be
> overridden by HTMLDIR variable inside Makefile.
> 
> To clear generated files one could use:
> 
> make clean-docs
> 
> Please review this patch and speak on.
> Is this enough for task "Put the bzr manual and bzr help output online"?
> Martin? Robert? What you think about this approach?
> 
> -- 
> Alexander
> 
> 

...

v- To avoid confusion, it should probably be called 'rst2html_wrapper.py'

> === added file tools/rst2html.py // file-id:rst2html.py-20060816094049-xl4x3vt2
> ... 8cjxymqt-1 // executable:yes
> --- /dev/null
> +++ tools/rst2html.py
> @@ -0,0 +1,63 @@
> +#!/usr/bin/env python
> +# Based on original rst2html.py by David Goodger
> +# Slightly reworked for Bazaar project
> +#
> +# Contact: goodger at python.org
> +# Revision: $Revision: 3901 $
> +# Date: $Date: 2005-09-25 17:49:54 +0200 (Sun, 25 Sep 2005) $
> +# Copyright: This module has been placed in the public domain.

^- This doesn't seem to have anything to do with rst2html.py, since it
just invokes the real rst2html. (I assume you were planning on copying
the real rst2html into the bazaar codebase and changed your mind).

Anyway, I would recommend removing the "Based on original..." stuff.

v- Doc string needs to be updated as well.
> +

...

> +    def invoke(args, shell=shell):
> +        q = Popen(args, stdout=PIPE, stderr=PIPE, shell=shell)
> +        output, error = q.communicate()
> +        status = q.wait()
> +        return status, output, error

^- The only problem with invoking rst2html.py in this way on Win32, is
that you have to have python associated with .py files, and not a text
editor, etc. I ran into this problem because I had 2.3 installed, which
was associated, and when I installed 2.4 it did not associate, so when I
uninstalled 2.3 all of my associations were gone. And I couldn't
manually associate for some reason. I had to re-install python 2.4.

So I would be a little bit happier doing something that knows that
rst2html.py is in Scripts near the python executable on win32. But I
don't require that.

...
> === modified file Makefile
> --- Makefile
> +++ Makefile
> @@ -44,9 +44,9 @@
>  htm_files := $(patsubst %.txt, %.htm, $(txt_files)) doc/bzr_man.htm
>  
>  %.htm: %.txt
> -	rst2html.py --link-stylesheet --stylesheet=default.css $*.txt $*.htm
> +	python tools/rst2html.py --link-stylesheet --stylesheet=default.css $*.txt $*.htm
>  
> -doc/bzr_man.txt:
> +doc/bzr_man.txt: generate_docs.py tools/doc_generate/__init__.py tools/doc_generate/autodoc_rstx.py
>  	python generate_docs.py -o doc/bzr_man.txt rstx
>  
>  docs: $(htm_files)
> @@ -54,6 +54,17 @@
>  copy_docs: docs
>  	python tools/win32/ostools.py copytodir $(htm_files) doc/default.css NEWS README  win32_bzr.exe/doc
>  
> +# Produce HTML docs to upload on Canonical server
> +HTMLDIR := html_docs
> +
> +htmldocs: docs
> +	python tools/win32/ostools.py copytodir $(htm_files) doc/default.css $(HTMLDIR)
> +
> +# clean produced docs
> +clean-docs:
> +	python tools/win32/ostools.py remove doc/bzr_man.txt $(htm_files) $(HTMLDIR)
> +
> +

There are some inconsistencies between the make commands:

make htmldocs
make copy_docs
make clean-docs

We should probably standardize on a naming scheme.

I like it in general. The only thing I would block on is the
tools/rst2html.py => tools/rst2html_wrapper.py

And I would *like* more consistent Make targets.

John
=:->


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 254 bytes
Desc: OpenPGP digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060816/decf1419/attachment.pgp