Skip to content

Commit ec6dc8f

Browse files
pgleesonpgleeson
authored
Merge pull request #4 from ModECI/development
Enable generation of RST documentation (WIP)
2 parents b5418a3 + 4ae7aef commit ec6dc8f

File tree

5 files changed

+198
-35
lines changed

5 files changed

+198
-35
lines changed

‎examples/document.md

Lines changed: 60 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,88 @@
11
## Document
2-
A model for documents
3-
#### Allowed parameters
4-
<table><tr><td><b>title</b></td><td>str</td><td><i>Document title</i></td></tr>
5-
6-
<tr><td><b>ISBN</b></td><td>int</td><td><i>International Standard Book Number</i></td></tr>
7-
8-
<tr><td><b>id</b></td><td>str</td><td><i>Unique ID of element</i></td></tr>
92

10-
<tr><td><b>notes</b></td><td>str</td><td><i>Human readable notes</i></td></tr>
3+
A model for documents
114

5+
### Allowed parameters
6+
<table>
7+
<tr>
8+
<td><b>title</b></td>
9+
<td>str</td>
10+
<td><i>Document title</i></td>
11+
</tr>
12+
13+
<tr>
14+
<td><b>ISBN</b></td>
15+
<td>int</td>
16+
<td><i>International Standard Book Number</i></td>
17+
</tr>
18+
19+
<tr>
20+
<td><b>id</b></td>
21+
<td>str</td>
22+
<td><i>Unique ID of element</i></td>
23+
</tr>
24+
25+
<tr>
26+
<td><b>notes</b></td>
27+
<td>str</td>
28+
<td><i>Human readable notes</i></td>
29+
</tr>
1230

1331
</table>
1432

1533
#### Allowed children
16-
<table><tr><td><b>sections</b></td><td><a href="#section">Section</a></td><td><i>The sections of the document</i></td></tr>
1734

35+
<table>
36+
<tr>
37+
<td><b>sections</b></td>
38+
<td><a href="#section">Section</a></td>
39+
<td><i>The sections of the document</i></td>
40+
</tr>
1841

1942
</table>
2043

2144
## Section
22-
A model of a section of the document
23-
#### Allowed parameters
24-
<table><tr><td><b>id</b></td><td>str</td><td><i>Unique ID of element</i></td></tr>
2545

26-
<tr><td><b>notes</b></td><td>str</td><td><i>Human readable notes</i></td></tr>
46+
A model of a section of the document. Will contain a <a href="#paragraph">Paragraph</a> or two
47+
48+
### Allowed parameters
49+
<table>
50+
<tr>
51+
<td><b>id</b></td>
52+
<td>str</td>
53+
<td><i>Unique ID of element</i></td>
54+
</tr>
2755

56+
<tr>
57+
<td><b>notes</b></td>
58+
<td>str</td>
59+
<td><i>Human readable notes</i></td>
60+
</tr>
2861

2962
</table>
3063

3164
#### Allowed children
32-
<table><tr><td><b>paragraphs</b></td><td><a href="#paragraph">Paragraph</a></td><td><i>The paragraphs</i></td></tr>
3365

66+
<table>
67+
<tr>
68+
<td><b>paragraphs</b></td>
69+
<td><a href="#paragraph">Paragraph</a></td>
70+
<td><i>The paragraphs</i></td>
71+
</tr>
3472

3573
</table>
3674

3775
## Paragraph
76+
3877
A model of a paragraph
39-
#### Allowed parameters
40-
<table><tr><td><b>contents</b></td><td>str</td><td><i>Paragraph contents</i></td></tr>
4178

79+
### Allowed parameters
80+
<table>
81+
<tr>
82+
<td><b>contents</b></td>
83+
<td>str</td>
84+
<td><i>Paragraph contents, which make up the <a href="#section">Section</a>s.</i></td>
85+
</tr>
4286

4387
</table>
4488

‎examples/document.py

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ def __init__(self, **kwargs):
2222

2323
class Section(BaseWithId):
2424

25-
_definition = "A model of a section of the document"
25+
_definition = "A model of a section of the document. Will contain a _Paragraph_ or two"
2626

2727
def __init__(self, **kwargs):
2828

@@ -37,7 +37,7 @@ class Paragraph(Base):
3737

3838
def __init__(self, **kwargs):
3939

40-
self.add_allowed_field("contents", "Paragraph contents", str)
40+
self.add_allowed_field("contents", "Paragraph contents, which make up the _Section_s.", str)
4141

4242
super(Paragraph, self).__init__(**kwargs)
4343

@@ -60,3 +60,8 @@ def __init__(self, **kwargs):
6060

6161
with open("document.md", "w") as d:
6262
d.write(doc_md)
63+
64+
doc_rst = doc.generate_documentation(format="rst")
65+
66+
with open("document.rst", "w") as d:
67+
d.write(doc_rst)

‎examples/document.rst

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
========
2+
Document
3+
========
4+
A model for documents
5+
6+
**Allowed parameters**
7+
8+
=============== =========== ====================================
9+
Allowed field Data Type Description
10+
=============== =========== ====================================
11+
**title** str *Document title*
12+
**ISBN** int *International Standard Book Number*
13+
**id** str *Unique ID of element*
14+
**notes** str *Human readable notes*
15+
=============== =========== ====================================
16+
17+
**Allowed children**
18+
19+
=============== ===================== ==============================
20+
Allowed child Data Type Description
21+
=============== ===================== ==============================
22+
**sections** `Section <#section>`_ *The sections of the document*
23+
=============== ===================== ==============================
24+
25+
=======
26+
Section
27+
=======
28+
A model of a section of the document. Will contain a Paragraph or two
29+
30+
**Allowed parameters**
31+
32+
=============== =========== ======================
33+
Allowed field Data Type Description
34+
=============== =========== ======================
35+
**id** str *Unique ID of element*
36+
**notes** str *Human readable notes*
37+
=============== =========== ======================
38+
39+
**Allowed children**
40+
41+
=============== ========================= ================
42+
Allowed child Data Type Description
43+
=============== ========================= ================
44+
**paragraphs** `Paragraph <#paragraph>`_ *The paragraphs*
45+
=============== ========================= ================
46+
47+
=========
48+
Paragraph
49+
=========
50+
A model of a paragraph
51+
52+
**Allowed parameters**
53+
54+
=============== =========== =================================================
55+
Allowed field Data Type Description
56+
=============== =========== =================================================
57+
**contents** str *Paragraph contents, which make up the Sections.*
58+
=============== =========== =================================================
59+

‎modelspec/BaseTypes.py

Lines changed: 71 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,13 @@
22
import json
33
import sys
44
from collections import OrderedDict
5+
from tabulate import tabulate
56

67
verbose = False
78

89
MARKDOWN_FORMAT = "markdown"
10+
RST_FORMAT = "rst"
11+
912
DICT_FORMAT = "dict"
1013

1114

@@ -369,14 +372,17 @@ def generate_documentation(self, format=MARKDOWN_FORMAT):
369372
Work in progress...
370373
"""
371374

372-
if format == MARKDOWN_FORMAT:
375+
if format == MARKDOWN_FORMAT or format == RST_FORMAT:
373376
doc_string = ""
374377
if format == DICT_FORMAT:
375378
doc_dict = {}
376379

377380
print(" - %s (%s)" % (self.__class__.__name__, self._definition))
378381

379-
def insert_links(text):
382+
rst_url_format = '`%s <%s>`_'
383+
384+
def insert_links(text, format=MARKDOWN_FORMAT):
385+
380386
if not "_" in text:
381387
return text
382388
if '"' in text:
@@ -386,24 +392,39 @@ def insert_links(text):
386392
for i in range(int(len(split) / 2.0)):
387393
pre = split[i * 2]
388394
type = split[i * 2 + 1]
389-
text2 += '%s<a href="#%s">%s</a>' % (pre, type.lower(), type)
395+
if format==MARKDOWN_FORMAT:
396+
text2 += '%s<a href="#%s">%s</a>' % (pre, type.lower(), type)
397+
elif format==RST_FORMAT:
398+
#text2 += ('%s'+rst_url_format) % (pre, type, '#'+type.lower # problem with handling links ending with s e.g. _Graph_s
399+
400+
text2 += ('%s%s') % (pre, type) # temp hack... problem with handling links ending with s e.g. _Graph_s
390401
if int(len(split) / 2.0) != len(split) / 2.0:
391402
text2 += split[-1]
392403
return text2
393404

394405
name = self.__class__.__name__
406+
395407
if format == MARKDOWN_FORMAT:
396-
doc_string += "## %s\n" % name
408+
doc_string += "## %s\n\n" % name
397409
if self._definition is not None:
398-
doc_string += "%s\n" % insert_links(self._definition)
399-
if format == DICT_FORMAT:
410+
doc_string += "%s\n\n" % insert_links(self._definition)
411+
elif format == RST_FORMAT:
412+
doc_string += "%s\n%s\n%s\n" % ("="*len(name),name,"="*len(name))
413+
if self._definition is not None:
414+
doc_string += "%s\n\n" % insert_links(self._definition, format = RST_FORMAT)
415+
416+
elif format == DICT_FORMAT:
400417
doc_dict[name] = {}
401418
if self._definition is not None:
402419
doc_dict[name]["definition"] = self._definition
403420

404421
if len(self.allowed_fields) > 0:
405422
if format == MARKDOWN_FORMAT:
406-
doc_string += "#### Allowed parameters\n<table>"
423+
doc_string += "### Allowed parameters\n<table>\n"
424+
if format == RST_FORMAT:
425+
ap = "**Allowed parameters**"
426+
doc_string += "%s\n\n" % (ap)
427+
table_info = []
407428
if format == DICT_FORMAT:
408429
doc_dict[name]["allowed_parameters"] = {}
409430

@@ -424,15 +445,26 @@ def insert_links(text):
424445
] = self.allowed_fields[f][0]
425446

426447
if format == MARKDOWN_FORMAT:
427-
doc_string += "<tr><td><b>%s</b></td><td>%s</td>" % (
448+
doc_string += " <tr>\n <td><b>%s</b></td>\n <td>%s</td>" % (
428449
f,
429450
'<a href="#%s">%s</a>' % (type_.lower(), type_)
430451
if referencable
431452
else type_,
432453
)
433-
doc_string += "<td><i>%s</i></td></tr>\n\n" % (
454+
doc_string += "\n <td><i>%s</i></td>\n </tr>\n\n" % (
434455
insert_links(self.allowed_fields[f][0])
435456
)
457+
if format == RST_FORMAT:
458+
n = "**%s**" % f
459+
t = "%s" % (
460+
rst_url_format % (type_, '#'+type_.lower())
461+
if referencable
462+
else type_,
463+
)
464+
d = "*%s*" % (
465+
insert_links(self.allowed_fields[f][0], format = RST_FORMAT)
466+
)
467+
table_info.append([n,t,d])
436468

437469
if referencable:
438470
inst = self.allowed_fields[f][1]()
@@ -441,11 +473,17 @@ def insert_links(text):
441473

442474
if len(self.allowed_fields) > 0:
443475
if format == MARKDOWN_FORMAT:
444-
doc_string += "\n</table>\n\n"
476+
doc_string += "</table>\n\n"
477+
if format == RST_FORMAT:
478+
doc_string += "%s\n\n"%(tabulate(table_info, ['Allowed field','Data Type','Description'], tablefmt="rst"))
445479

446480
if len(self.allowed_children) > 0:
447481
if format == MARKDOWN_FORMAT:
448-
doc_string += "#### Allowed children\n<table>"
482+
doc_string += "#### Allowed children\n\n<table>\n"
483+
if format == RST_FORMAT:
484+
ap = "**Allowed children**"
485+
doc_string += "%s\n\n" % (ap)
486+
table_info = []
449487
if format == DICT_FORMAT:
450488
doc_dict[name]["allowed_children"] = {}
451489

@@ -466,32 +504,49 @@ def insert_links(text):
466504
] = self.allowed_children[c][0]
467505

468506
if format == MARKDOWN_FORMAT:
469-
doc_string += "<tr><td><b>%s</b></td><td>%s</td>" % (
507+
doc_string += " <tr>\n <td><b>%s</b></td>\n <td>%s</td>" % (
470508
c,
471509
'<a href="#%s">%s</a>' % (type_.lower(), type_)
472510
if referencable
473511
else type_,
474512
)
475-
doc_string += "<td><i>%s</i></td></tr>\n\n" % (
513+
doc_string += "\n <td><i>%s</i></td>\n </tr>\n\n" % (
476514
insert_links(self.allowed_children[c][0])
477515
)
478516

517+
if format == RST_FORMAT:
518+
n = "**%s**" % c
519+
t = "%s" % (
520+
rst_url_format % (type_, '#'+type_.lower())
521+
if referencable
522+
else type_,
523+
)
524+
d = "*%s*" % (
525+
insert_links(self.allowed_children[c][0], format = RST_FORMAT)
526+
)
527+
table_info.append([n,t,d])
528+
529+
479530
inst = self.allowed_children[c][1]()
480531
inst.id = ""
481532
referenced.append(inst)
482533

483534
if len(self.allowed_children) > 0:
484535
if format == MARKDOWN_FORMAT:
485-
doc_string += "\n</table>\n\n"
536+
doc_string += "</table>\n\n"
537+
538+
if len(self.allowed_children) > 0:
539+
if format == RST_FORMAT:
540+
doc_string += "%s\n\n"%(tabulate(table_info, ['Allowed child','Data Type','Description'], tablefmt="rst"))
486541

487542
for r in referenced:
488-
if format == MARKDOWN_FORMAT:
543+
if format == MARKDOWN_FORMAT or format== RST_FORMAT:
489544
doc_string += r.generate_documentation(format=format)
490545
if format == DICT_FORMAT:
491546
pass
492547
doc_dict.update(r.generate_documentation(format=format))
493548

494-
if format == MARKDOWN_FORMAT:
549+
if format == MARKDOWN_FORMAT or format== RST_FORMAT:
495550
return doc_string
496551
if format == DICT_FORMAT:
497552
return doc_dict

‎setup.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
description="A common JSON/YAML based format for compact model specification",
1616
long_description=open("README.md").read(),
1717
long_description_content_type="text/markdown",
18-
install_requires=["pyyaml", "numpy"],
18+
install_requires=["pyyaml", "numpy", "tabulate"],
1919
classifiers=[
2020
"Intended Audience :: Science/Research",
2121
"License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",

0 commit comments

Comments
 (0)