4 # Author: David Goodger <goodger@python.org>
5 # Copyright: This module has been placed in the public domain.
8 Generates .html from all the .txt files in a directory.
10 Ordinary .txt files are understood to be standalone reStructuredText.
11 Files named ``pep-*.txt`` are interpreted as reStructuredText PEPs.
13 # Once PySource is here, build .html from .py as well.
15 __docformat__
= 'reStructuredText'
20 locale
.setlocale(locale
.LC_ALL
, '')
28 from fnmatch
import fnmatch
30 from docutils
import ApplicationError
31 from docutils
import core
, frontend
, utils
32 from docutils
.error_reporting
import ErrorOutput
, ErrorString
33 from docutils
.parsers
import rst
34 from docutils
.readers
import standalone
, pep
35 from docutils
.writers
import html4css1
, pep_html
38 usage
= '%prog [options] [<directory> ...]'
39 description
= ('Generates .html from all the reStructuredText .txt files '
40 '(including PEPs) in each <directory> '
41 '(default is the current directory).')
44 class SettingsSpec(docutils
.SettingsSpec
):
47 Runtime settings & command-line options for the front end.
50 # Can't be included in OptionParser below because we don't want to
51 # override the base class.
55 (('Recursively scan subdirectories for files to process. This is '
58 {'action': 'store_true', 'default': 1,
59 'validator': frontend
.validate_boolean
}),
60 ('Do not scan subdirectories for files to process.',
61 ['--local'], {'dest': 'recurse', 'action': 'store_false'}),
62 ('BROKEN Do not process files in <directory>. This option may be used '
63 'more than once to specify multiple directories.',
65 {'metavar': '<directory>', 'action': 'append',
66 'validator': frontend
.validate_colon_separated_string_list
}),
67 ('BROKEN Recursively ignore files or directories matching any of the given '
68 'wildcard (shell globbing) patterns (separated by colons). '
69 'Default: ".svn:CVS"',
71 {'metavar': '<patterns>', 'action': 'append',
72 'default': ['.svn', 'CVS'],
73 'validator': frontend
.validate_colon_separated_string_list
}),
74 ('Work silently (no progress messages). Independent of "--quiet".',
76 {'action': 'store_true', 'validator': frontend
.validate_boolean
}),
77 ('Do not process files, show files that would be processed.',
79 {'action': 'store_true', 'validator': frontend
.validate_boolean
}),))
81 relative_path_settings
= ('prune',)
82 config_section
= 'buildhtml application'
83 config_section_dependencies
= ('applications',)
86 class OptionParser(frontend
.OptionParser
):
89 Command-line option processing for the ``buildhtml.py`` front end.
92 def check_values(self
, values
, args
):
93 frontend
.OptionParser
.check_values(self
, values
, args
)
97 def check_args(self
, args
):
98 source
= destination
= None
100 self
.values
._directories
= args
102 self
.values
._directories
= [os
.getcwd()]
103 return source
, destination
108 """Stores data attributes for dotted-attribute access."""
110 def __init__(self
, **keywordargs
):
111 self
.__dict
__.update(keywordargs
)
118 '': Struct(components
=(pep
.Reader
, rst
.Parser
, pep_html
.Writer
,
120 '.txt': Struct(components
=(rst
.Parser
, standalone
.Reader
,
121 html4css1
.Writer
, SettingsSpec
),
122 reader_name
='standalone',
124 'PEPs': Struct(components
=(rst
.Parser
, pep
.Reader
,
125 pep_html
.Writer
, SettingsSpec
),
127 writer_name
='pep_html')}
128 """Publisher-specific settings. Key '' is for the front-end script
129 itself. ``self.publishers[''].components`` must contain a superset of
130 all components used by individual publishers."""
132 self
.setup_publishers()
134 def setup_publishers(self
):
136 Manage configurations for individual publishers.
138 Each publisher (combination of parser, reader, and writer) may have
139 its own configuration defaults, which must be kept separate from those
140 of the other publishers. Setting defaults are combined with the
141 config file settings and command-line options by
142 `self.get_settings()`.
144 for name
, publisher
in self
.publishers
.items():
145 option_parser
= OptionParser(
146 components
=publisher
.components
, read_config_files
=1,
147 usage
=usage
, description
=description
)
148 publisher
.option_parser
= option_parser
149 publisher
.setting_defaults
= option_parser
.get_default_values()
150 frontend
.make_paths_absolute(publisher
.setting_defaults
.__dict
__,
151 option_parser
.relative_path_settings
)
152 publisher
.config_settings
= (
153 option_parser
.get_standard_config_settings())
154 self
.settings_spec
= self
.publishers
[''].option_parser
.parse_args(
155 values
=frontend
.Values()) # no defaults; just the cmdline opts
156 self
.initial_settings
= self
.get_settings('')
158 def get_settings(self
, publisher_name
, directory
=None):
160 Return a settings object, from multiple sources.
162 Copy the setting defaults, overlay the startup config file settings,
163 then the local config file settings, then the command-line options.
164 Assumes the current directory has been set.
166 publisher
= self
.publishers
[publisher_name
]
167 settings
= frontend
.Values(publisher
.setting_defaults
.__dict
__)
168 settings
.update(publisher
.config_settings
, publisher
.option_parser
)
170 local_config
= publisher
.option_parser
.get_config_file_settings(
171 os
.path
.join(directory
, 'docutils.conf'))
172 frontend
.make_paths_absolute(
173 local_config
, publisher
.option_parser
.relative_path_settings
,
175 settings
.update(local_config
, publisher
.option_parser
)
176 settings
.update(self
.settings_spec
.__dict
__, publisher
.option_parser
)
179 def run(self
, directory
=None, recurse
=1):
180 recurse
= recurse
and self
.initial_settings
.recurse
182 self
.directories
= [directory
]
183 elif self
.settings_spec
._directories
:
184 self
.directories
= self
.settings_spec
._directories
186 self
.directories
= [os
.getcwd()]
187 for directory
in self
.directories
:
188 for root
, dirs
, files
in os
.walk(directory
):
189 # os.walk by default this recurses down the tree,
190 # influence by modifying dirs.
193 self
.visit(root
, files
)
195 def visit(self
, directory
, names
):
196 # BUG prune and ignore do not work
197 settings
= self
.get_settings('', directory
)
198 errout
= ErrorOutput(encoding
=settings
.error_encoding
)
199 if settings
.prune
and (os
.path
.abspath(directory
) in settings
.prune
):
200 print >>errout
, ('/// ...Skipping directory (pruned): %s' %
205 if not self
.initial_settings
.silent
:
206 print >>errout
, '/// Processing directory: %s' % directory
208 # settings.ignore grows many duplicate entries as we recurse
209 # if we add patterns in config files or on the command line.
210 for pattern
in utils
.uniq(settings
.ignore
):
211 for i
in range(len(names
) - 1, -1, -1):
212 if fnmatch(names
[i
], pattern
):
217 if name
.endswith('.txt'):
218 prune
= self
.process_txt(directory
, name
)
222 def process_txt(self
, directory
, name
):
223 if name
.startswith('pep-'):
227 settings
= self
.get_settings(publisher
, directory
)
228 errout
= ErrorOutput(encoding
=settings
.error_encoding
)
229 pub_struct
= self
.publishers
[publisher
]
230 if settings
.prune
and (directory
in settings
.prune
):
232 settings
._source
= os
.path
.normpath(os
.path
.join(directory
, name
))
233 settings
._destination
= settings
._source
[:-4]+'.html'
234 if not self
.initial_settings
.silent
:
235 print >>errout
, ' ::: Processing: %s' % name
238 if not settings
.dry_run
:
239 core
.publish_file(source_path
=settings
._source
,
240 destination_path
=settings
._destination
,
241 reader_name
=pub_struct
.reader_name
,
242 parser_name
='restructuredtext',
243 writer_name
=pub_struct
.writer_name
,
245 except ApplicationError
, error
:
246 print >>errout
, ' %s' % ErrorString(error
)
249 if __name__
== "__main__":