Skip to content

Commit

Permalink
DOCS-1523: tables of contents generation
Browse files Browse the repository at this point in the history
  • Loading branch information
Sam Kleinman committed May 16, 2013
1 parent 2859dfc commit 9737a10
Show file tree
Hide file tree
Showing 4 changed files with 103 additions and 43 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ source/includes/hash.rst
source/includes/install-curl-release*.rst
source/includes/table-*.rst
source/includes/toc-*.rst
source/includes/dfn*.rst
source/includes/manpage-options-auth-mongo.rst
source/includes/manpage-options-ssl-settings.rst
TAGS
Expand Down
2 changes: 1 addition & 1 deletion bin/makecloth/sphinx.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ def make_all_sphinx(sphinx):
m.target('sphinx-prerequisites', 'setup composites generate-source composite-pages.yaml', block='prereq')
m.msg('[sphinx-prep]: completed $@ buildstep.', block='prereq')

m.target('generate-source', '$(branch-output)/source images tables installation-guides intersphinx generate-manpages api ref-toc', block='prereq')
m.target('generate-source', '$(branch-output)/source images tables installation-guides intersphinx generate-manpages api toc', block='prereq')
m.job('rsync --recursive --times --delete source/ $(branch-output)/source', block='prereq')
m.msg('[sphinx-prep]: updated source in $(branch-output)/source', block='prereq')
info_note = 'Build in progress past critical phase.'
Expand Down
73 changes: 51 additions & 22 deletions bin/makecloth/toc.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,44 +10,73 @@

m = MakefileCloth()

def make_toc():
inputs = [i for i in util.expand_tree('./source/includes') if i.startswith('./source/includes/ref-toc-') ]
def make_toc(sources):
for target in sources:
document = target[0]
output_format = target[1]

if document.startswith('./source/includes/ref-toc-'):
base_name = document.rsplit('/', 1)[1].rsplit('.', 1)[0][8:]
if document.startswith('./source/includes/toc-'):
base_name = document.rsplit('/', 1)[1].rsplit('.', 1)[0][4:]

for document in inputs:
document = document[2:]

base_name = document.rsplit('/', 1)[1].rsplit('.', 1)[0][8:]

m.section_break(document)

table_target = 'source/includes/table-' + base_name + '.rst'
m.append_var('ref-toc-output', table_target, block=base_name)
m.target(target=table_target,
dependency=[document, 'bin/rstcloth/toc.py'], block=base_name)
m.job('$(PYTHONBIN) bin/rstcloth/toc.py $< --table $@', block=base_name)
m.msg('[toc-builder]: built table file for %s' % base_name, block=base_name)

m.newline()
if 'table' in output_format:
table_target = 'source/includes/table-' + base_name + '.rst'
m.append_var('toc-output', table_target, block=base_name)
m.target(target=table_target,
dependency=[document, 'bin/rstcloth/toc.py'], block=base_name)
m.job('$(PYTHONBIN) bin/rstcloth/toc.py $< --table $@', block=base_name)
m.msg('[toc-builder]: built table file for %s' % base_name, block=base_name)
m.newline()

if 'dfn' in output_format:
table_target = 'source/includes/dfn-list-' + base_name + '.rst'
m.append_var('toc-output', table_target, block=base_name)
m.target(target=table_target,
dependency=[document, 'bin/rstcloth/toc.py'], block=base_name)
m.job('$(PYTHONBIN) bin/rstcloth/toc.py $< --dfn $@', block=base_name)
m.msg('[toc-builder]: built definition list file for %s' % base_name, block=base_name)
m.newline()

toc_target = 'source/includes/toc-' + base_name + '.rst'
m.append_var('ref-toc-output', toc_target, block=base_name)
m.append_var('toc-output', toc_target, block=base_name)
m.target(target=toc_target,
dependency=[document, 'bin/rstcloth/toc.py'], block=base_name)
m.job('$(PYTHONBIN) bin/rstcloth/toc.py $< --contents $@', block=base_name)
m.msg('[toc-builder]: built toctree file for %s' % base_name, block=base_name)
m.newline()

def generate_footer():
m.section_break('meta')
m.target('.PHONY', ['clean-ref-toc', 'ref-toc', 'reftoc', 'clean-reftoc'], block='meta')
m.target(['ref-toc', 'reftoc'], '$(ref-toc-output)', block='meta')
m.target(['clean-ref-toc', 'clean-reftoc'], block='meta')
m.job('rm -f $(ref-toc-output)', ignore=True)
m.msg('[toc-builder]: cleaned all ref-toc build products.')

m.target('.PHONY', ['clean-toc', 'toc'], block='meta')
m.target('toc', '$(toc-output)', block='meta')
m.target(['clean-toc', 'clean-reftoc'], block='meta')
m.job('rm -f $(toc-output)', ignore=True)
m.msg('[toc-builder]: cleaned all toc build products.')

def collect_source_files():
output = []

for i in util.expand_tree('./source/includes', 'yaml'):
if i.startswith('./source/includes/ref-toc-'):
output.append((i, 'table'))
if i.startswith('./source/includes/toc-'):
output.append((i, 'dfn'))

return output

def main():
make_toc()
sources = collect_source_files()
make_toc(sources)

generate_footer()
m.write(sys.argv[1])

print('[meta-build]: built "' + sys.argv[1] + '" to specify reference toc data builders.')
print('[meta-build]: built "' + sys.argv[1] + '" to specify reference toc builders.')


if __name__ == '__main__':
Expand Down
70 changes: 50 additions & 20 deletions bin/rstcloth/toc.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,27 @@
import table as tb
from rstcloth import RstCloth, fill

class ReferenceToc(object):
class CustomTocTree(object):
def __init__(self, filename):
self.spec = self._process_spec(filename)

self.table = None
self.contents = None
self.dfn = None

def build_table(self):
self.table = tb.TableData()
self.content = RstCloth()
self.table.add_header(['Name', 'Description'])

self.spec = self._process_spec(filename)
self._process_data()
def build_dfn(self):
self.dfn = RstCloth()

def build_contents(self):
self.contents = RstCloth()
self.contents.directive('class', 'hidden')
self.contents.newline()
self.contents.directive('toctree', fields=[('titlesonly', '')], indent=3)
self.contents.newline()

def _process_spec(self, spec):
o = []
Expand All @@ -30,41 +44,57 @@ def _process_spec(self, spec):

return o

def _process_data(self):
self.table.add_header(['Name', 'Description'])

self.content.directive('class', 'hidden', block='toc')
self.content.newline(block='toc')
self.content.directive('toctree', fields=[('titlesonly', '')], indent=3, block='toc')
self.content.newline(block='toc')

def finalize(self):
for ref in self.spec:
self.content.content(ref['file'], 6, block='toc')
self.table.add_row([ ref['name'], ref['description'] ])
if self.table is not None:
self.table.add_row([ ref['name'], ref['description'] ])
if self.contents is not None:
self.contents.content(ref['file'], 6, block='toc')
if self.dfn is not None:
if 'name' in ref:
text = ref['name']
else:
text = None

link = self.dfn.role('doc', ref['file'], text)
self.dfn.definition(link, ref['description'], bold=False)
self.dfn.newline()

def user_input():
parser = argparse.ArgumentParser('.htaccess generator.')

parser.add_argument('filename', nargs='?',
help='the input data file.')
parser.add_argument('--table', '-t', action='store', default=None,
parser.add_argument('--table', '-t', action='store', default=False,
help='output filename for table.')
parser.add_argument('--contents', '-c', action='store', default=None,
parser.add_argument('--contents', '-c', action='store', default=False,
help='output filename for toctree.')
parser.add_argument('--dfn', '-d', action='store', default=False,
help='output filename for definition list.')

return parser.parse_args()

def main():
ui = user_input()

toc = ReferenceToc(ui.filename)
toc = CustomTocTree(ui.filename)

if ui.dfn:
toc.build_dfn()
if ui.contents:
toc.build_contents()
if ui.table:
t = tb.TableBuilder(tb.RstTable(toc.table))
t.write(ui.table)
toc.build_table()

toc.finalize()

if ui.dfn:
toc.dfn.write(ui.dfn)
if ui.contents:
toc.content.write(ui.contents)
toc.contents.write(ui.contents)
if ui.table:
t = tb.TableBuilder(tb.RstTable(toc.table))
t.write(ui.table)

if __name__ == '__main__':
main()

0 comments on commit 9737a10

Please sign in to comment.