Mercurial > pylearn
annotate doc/ext.py @ 1107:e5306f5626d4
architecture: Yet another rant, this time about encapsulation vs. linearization
| author | Olivier Delalleau <delallea@iro> |
|---|---|
| date | Mon, 13 Sep 2010 22:45:10 -0400 |
| parents | 7edb78ba4c5b |
| children |
| rev | line source |
|---|---|
| 912 | 1 |
| 2 import sys | |
| 3 import re | |
| 4 import os | |
| 5 from docutils import nodes, utils | |
| 6 from docutils.parsers.rst import roles | |
| 7 import epydoc.docwriter.xlink as xlink | |
| 8 | |
|
913
7edb78ba4c5b
Changed epy.doc slightly; commented a part concerning a wiki which does not seem to exist anymore; changed THEANO_API_ROOT to PYLEARN_API_ROOT
fsavard
parents:
912
diff
changeset
|
9 #def role_fn(name, rawtext, text, lineno, inliner, |
|
7edb78ba4c5b
Changed epy.doc slightly; commented a part concerning a wiki which does not seem to exist anymore; changed THEANO_API_ROOT to PYLEARN_API_ROOT
fsavard
parents:
912
diff
changeset
|
10 # options={}, content=[]): |
|
7edb78ba4c5b
Changed epy.doc slightly; commented a part concerning a wiki which does not seem to exist anymore; changed THEANO_API_ROOT to PYLEARN_API_ROOT
fsavard
parents:
912
diff
changeset
|
11 # node = nodes.reference(rawtext, text, refuri = "http://pylearn.org/theano/wiki/%s" % text) |
|
7edb78ba4c5b
Changed epy.doc slightly; commented a part concerning a wiki which does not seem to exist anymore; changed THEANO_API_ROOT to PYLEARN_API_ROOT
fsavard
parents:
912
diff
changeset
|
12 # return [node], [] |
| 912 | 13 |
| 14 | |
| 15 _TARGET_RE = re.compile(r'^(.*?)\s*<(?:URI:|URL:)?([^<>]+)>$') | |
| 16 def create_api_role(name, problematic): | |
| 17 """ | |
| 18 Create and register a new role to create links for an API documentation. | |
| 19 | |
| 20 Create a role called `name`, which will use the URL resolver registered as | |
| 21 ``name`` in `api_register` to create a link for an object. | |
| 22 | |
| 23 :Parameters: | |
| 24 `name` : `str` | |
| 25 name of the role to create. | |
| 26 `problematic` : `bool` | |
| 27 if True, the registered role will create problematic nodes in | |
| 28 case of failed references. If False, a warning will be raised | |
| 29 anyway, but the output will appear as an ordinary literal. | |
| 30 """ | |
| 31 def resolve_api_name(n, rawtext, text, lineno, inliner, | |
| 32 options={}, content=[]): | |
| 33 | |
| 34 # Check if there's separate text & targets | |
| 35 m = _TARGET_RE.match(text) | |
| 36 if m: text, target = m.groups() | |
| 37 else: target = text | |
| 38 | |
| 39 # node in monotype font | |
| 40 text = utils.unescape(text) | |
| 41 node = nodes.literal(rawtext, text, **options) | |
| 42 | |
| 43 # Get the resolver from the register and create an url from it. | |
| 44 try: | |
| 45 url = xlink.api_register[name].get_url(target) | |
| 46 except IndexError, exc: | |
| 47 msg = inliner.reporter.warning(str(exc), line=lineno) | |
| 48 if problematic: | |
| 49 prb = inliner.problematic(rawtext, text, msg) | |
| 50 return [prb], [msg] | |
| 51 else: | |
| 52 return [node], [] | |
| 53 | |
| 54 if url is not None: | |
| 55 node = nodes.reference(rawtext, '', node, refuri=url, **options) | |
| 56 return [node], [] | |
| 57 | |
| 58 roles.register_local_role(name, resolve_api_name) | |
| 59 | |
| 60 | |
| 61 def setup(app): | |
| 62 | |
| 63 try: | |
| 64 xlink.set_api_file('api', os.path.join(app.outdir, 'api', 'api-objects.txt')) | |
|
913
7edb78ba4c5b
Changed epy.doc slightly; commented a part concerning a wiki which does not seem to exist anymore; changed THEANO_API_ROOT to PYLEARN_API_ROOT
fsavard
parents:
912
diff
changeset
|
65 apiroot = os.getenv('PYLEARN_API_ROOT') |
| 912 | 66 if not apiroot: |
| 67 apiroot = os.path.join(os.path.realpath('api'), '') | |
| 68 xlink.set_api_root('api', apiroot) | |
| 69 #xlink.create_api_role('api', True) | |
| 70 create_api_role('api', True) | |
| 71 except IOError: | |
| 72 print >>sys.stderr, 'WARNING: Could not find api file! API links will not work.' | |
| 73 | |
|
913
7edb78ba4c5b
Changed epy.doc slightly; commented a part concerning a wiki which does not seem to exist anymore; changed THEANO_API_ROOT to PYLEARN_API_ROOT
fsavard
parents:
912
diff
changeset
|
74 #app.add_role("wiki", role_fn) |
|
7edb78ba4c5b
Changed epy.doc slightly; commented a part concerning a wiki which does not seem to exist anymore; changed THEANO_API_ROOT to PYLEARN_API_ROOT
fsavard
parents:
912
diff
changeset
|
75 |