On Wed, Dec 07, 2005 at 10:50:32AM +0100, Stefane Fermigier wrote:
> For those who didn't notice in the commits, Dave Kuhlman (in cc: of this
> mail) is reformatting the internal (doc/ directories in the packages)
> documentation to nice ReStructuredText, and also sometimes rewriting /
> improving it.
>
> Two remarks:
>
> 1. Thanks Dave!
>
You're welcome. It's more fun than you'd think. OK, not that
much fun, but it is educational.
> 2. In the future, let's try to format the document right in the first
> place, and check that they look right by compiling them with rst2html
> (we could even add Makefiles for that).
>
> For ReST documentation, I found these documents quite helpful:
>
> http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt
> http://docutils.sourceforge.net/docs/user/rst/quickref.html
>
I've added a few notes below that give the most common formatting
conventions that I'm using. If we have hopes of building a single
document or even a consistent looking collection of documents, it
would be nice if everyone follows a set of conventions such as
these. Let me know if any of these seem objectionable.
Also, it will be helpful if we all use the same style sheet
located at CPSDefault/doc/nuxeo_doc.css.
And, for what it's worth ...
I've also attached a small Python script that I use for building
HTML. It may (or may not) be convenient to use this script while
editing your documents. It's a special purpose, mini-make. When
run in a directory CPS*/doc/, it builds HTML for any out of date
or missing HTML files, adding the CPSDefault/doc/nuxeo_doc.css
style sheet. A -f flag forces builds, and a -v flag prints a bit
more info. Without arguments, it processes all *.txt files in the
current directory.
At some time in the future, perhaps we will have a real Makefile
in each /doc/ directory or some other mechanism for building
documentation in several formats (e.g. HTML, PDF) from all source
files in a single operation.
Dave
Formatting conventions follow --
============================
reStructuredText Conventions
============================
Titles:
- Document title: "=" over and under.
- Level 1: "=" under.
- Level 2: "-" (dash) under.
- Level 3: "." (dot/period) under.
Bullet lists:
- Level 1: "-" (dash)
- Level 2: "+"
- Level 3: "*" (star)
Enumerated lists: 1., 2., ...
Code samples: "::" (double colon), followed by a blank line and
indent the code.
In-line literals and in-line code: "``" (double back-ticks) --
Example: ``print "Hello, %s" %s name``.
Add the following near the top of the document (after the document
title). It will generate a numbered table of contents near the top
of the document::
:Revision: $Id$
.. sectnum:: :depth: 4
.. contents:: :depth: 4
--
Dave Kuhlman
http://www.rexx.com/~dkuhlman
#!/usr/bin/env python
"""
Build HTML files from CPS*/doc/*.txt files.
This is a special purpose, mini-make. When run in a directory
CPS*/doc/, it builds HTML that is out of date or missing. A -f
flag forces builds, and a -v flag prints a bit more info. Without
arguments, it processes all *.txt files in the current directory.
"""
import sys
import getopt
import os
import glob
StylesheetPath = "../../CPSDefault/doc/nuxeo_doc.css"
CommandTmpl = "rst2html.py --source-url=%%s.txt " \
"--generator %%s.txt " \
"--stylesheet-path=%s " \
"%%s.html"
def generate(fileNameList, command, force, verbose):
buildCount = 0
if not fileNameList:
fileNameList = glob.glob('*.txt')
if verbose:
print 'Files to (possibly) be processed:'
for fileName in fileNameList:
print ' %s' % fileName
for fileName in fileNameList:
path, ext = os.path.splitext(fileName)
if ext != '.txt':
print '*** Error. Not a .txt file. Skipping: %s' % fileName
continue
htmlFileName = '%s.html' % path
txtFileName = fileName
if force:
process(path, command)
buildCount += 1
else:
if not os.path.exists(htmlFileName):
process(path, command)
buildCount += 1
elif mdate(htmlFileName) < mdate(txtFileName):
process(path, command)
buildCount += 1
if verbose:
print 'Built %d files.' % buildCount
def mdate(pathName):
return os.stat(pathName)[8]
def process(path, command):
cmd = command % (path, path, path, )
print cmd
os.system(cmd)
USAGE_TEXT = """
Usage:
python generate_cps.py [options] [file.txt file.txt ...]
Options:
-h, --help Display this help message.
-f, --force Force. Re-build all files unconditionally.
-v, --verbose Verbose. Print extra info.
-s, --stylesheet Stylesheet path.
Examples:
python generate_cps.py
python generate_cps.py file1.txt file2.txt
python generate_cps.py -f -v file1.txt file2.txt
"""
def usage():
print USAGE_TEXT
sys.exit(-1)
def main():
args = sys.argv[1:]
try:
opts, args = getopt.getopt(args, 'hfvs:',
['help', 'force', 'verbose', 'stylesheet=', ])
except:
usage()
force = False
verbose = False
stylesheet = StylesheetPath
for opt, val in opts:
if opt in ('-h', '--help'):
usage()
elif opt in ('-f', '--force'):
force = True
elif opt in ('-v', '--verbose'):
verbose = True
elif opt in ('-s', '--stylesheet'):
stylesheet = val
if not os.path.exists(stylesheet):
print "Can't find stylesheet: %s." % (stylesheet, )
print 'Use -s flag or be in a CPS*/doc/ directory.'
print 'Aborting.'
sys.exit(-1)
command = CommandTmpl % (stylesheet, )
generate(args, command, force, verbose)
if __name__ == '__main__':
main()
#import pdb
#pdb.run('main()')
_______________________________________________
cps-devel mailing list
http://lists.nuxeo.com/mailman/listinfo/cps-devel
