Howard Butler schrieb:
> First off, thanks so much for Sphinx. You can add MapServer
> <http://mapserver.osgeo.org
> > to the list of projects using Sphinx for its documentation. We
> have over 200 files of docs that eventually ends up being over 600
> pages of PDF when generated by LaTeX. Sphinx and reStructuredText are
> a fantastic way to manage it all.
>
> One thing that is challenging to manage with so much documentation is
> the referencing. We're using :ref: with labels
> <http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations
>
> > all over the place. When writers write docs, one thing they need
> to be able to do to make their documents stronger is add lots of
> linking using the :ref:'s, but you have to know what the reference
> names are before you can call them. It would be very handy to collect
> all of the :ref: names and their titles into a reStructuredText table
> that could be included in the documentation somewhere so authors have
> a primer when writing/editing their docs.
>
> Is this currently possible without too much trouble? Would I need to
> write an custom extension/builder to do it? Are there any examples to
> follow?
>
> Thanks for any pointers, and Sphinx kicks ass.
Thanks for the praise!
Yes, this is possible, either as a separate builder, like this:
from os import path
from itertools import groupby
from sphinx.builder import Builder
class CollectLabelsBuilder(Builder):
"""
Collects all present explicit labels into a table.
"""
name = 'labels'
def init(self):
pass
def get_outdated_docs(self):
return "table with all labels"
def write(self, *ignored):
labels = self.env.labels.items()
labels.sort(key=lambda x: x[1])
outfile = open(path.join(self.outdir, 'labels.txt'), 'w')
for docname, items in groupby(labels, key=lambda x: x[1][0]):
outfile.write('Labels in %s\n%s\n' % (docname, '-' * (len(docname) +
10)))
for label in items:
outfile.write('%s %s\n' % (label[0].ljust(30), label[1][2]))
outfile.write('\n')
outfile.close()
def finish(self):
return
def setup(app):
app.add_builder(CollectLabelsBuilder)
In this case, you have to call it explicitly. Another possibility is a handler
that's called at build finish time:
def handle_finished(app, error):
labels = app.builder.env.labels.items()
labels.sort(key=lambda x: x[1])
outfile = open(path.join(app.builder.srcdir, 'labels.txt'), 'w')
for docname, items in groupby(labels, key=lambda x: x[1][0]):
outfile.write('Labels in %s\n%s\n' % (docname, '-' * (len(docname) +
10)))
for label in items:
outfile.write('%s %s\n' % (label[0].ljust(30), label[1][2]))
outfile.write('\n')
outfile.close()
def setup(app):
app.connect('build-finished', handle_finished)
cheers,
Georg
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
