Skip to content

Commit a4b6f27

Browse files
pgleesonpgleeson
authored
Merge pull request #9 from ModECI/development
Update formatting of generated docs
2 parents 35c23e0 + 75d7ea6 commit a4b6f27

File tree

7 files changed

+103
-32
lines changed

7 files changed

+103
-32
lines changed

‎README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Modelspec
22

3-
Functionality for specifying models & enabling automatic serialization is being moved here from https://github.com/NeuroML/NeuroMLlite.
3+
Functionality for specifying models & enabling automatic serialization (e.g. in JSON and YAML format).
44

5-
This package will be used by NeuroMLlite & [MDF](https://github.com/ModECI/MDF/actions).
5+
This package is being used by [NeuroMLlite](https://github.com/NeuroML/NeuroMLlite) & [MDF](https://github.com/ModECI/MDF).
66

77

88
[![Continuous builds](https://github.com/ModECI/modelspec/actions/workflows/ci.yml/badge.svg)](https://github.com/ModECI/modelspec/actions/workflows/ci.yml)

‎examples/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## Some simple examples of the use of Modelspec
2+
3+
See also packages [NeuroMLlite](https://github.com/NeuroML/NeuroMLlite) & [MDF](https://github.com/ModECI/MDF) for usage of Modelspec.

‎examples/document.md

Lines changed: 48 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,77 @@
11
## Document
22
A model for documents
33

4-
#### Allowed parameters
5-
<table><tr><td><b>id</b></td><td>str</td><td><i>The unique id of the document</i></td></tr>
4+
### Allowed parameters
5+
<table>
6+
<tr>
7+
<td><b>id</b></td>
8+
<td>str</td>
9+
<td><i>The unique id of the document</i></td>
10+
</tr>
611

7-
<tr><td><b>title</b></td><td>str</td><td><i>Document title</i></td></tr>
812

9-
<tr><td><b>ISBN</b></td><td>int</td><td><i>International Standard Book Number</i></td></tr>
13+
<tr>
14+
<td><b>title</b></td>
15+
<td>str</td>
16+
<td><i>Document title</i></td>
17+
</tr>
18+
19+
20+
<tr>
21+
<td><b>ISBN</b></td>
22+
<td>int</td>
23+
<td><i>International Standard Book Number</i></td>
24+
</tr>
1025

1126

1227
</table>
1328

14-
#### Allowed children
15-
<table><tr><td><b>sections</b></td><td><a href="#section">Section</a></td><td><i>The sections of the document</i></td></tr>
29+
### Allowed children
30+
<table>
31+
<tr>
32+
<td><b>sections</b></td>
33+
<td><a href="#section">Section</a></td>
34+
<td><i>The sections of the document</i></td>
35+
</tr>
1636

1737

1838
</table>
1939

2040
## Section
21-
A model of a section of the document. Will contain a <a href="#paragraph">Paragraph</a> or two
41+
A model of a section of the <a href="#document">Document</a>. Will contain one <a href="#paragraph">Paragraph</a> or more
2242

23-
#### Allowed parameters
24-
<table><tr><td><b>id</b></td><td>str</td><td><i>The id of the section</i></td></tr>
43+
### Allowed parameters
44+
<table>
45+
<tr>
46+
<td><b>id</b></td>
47+
<td>str</td>
48+
<td><i>The id of the section</i></td>
49+
</tr>
2550

2651

2752
</table>
2853

29-
#### Allowed children
30-
<table><tr><td><b>paragraphs</b></td><td><a href="#paragraph">Paragraph</a></td><td><i>The paragraphs</i></td></tr>
54+
### Allowed children
55+
<table>
56+
<tr>
57+
<td><b>paragraphs</b></td>
58+
<td><a href="#paragraph">Paragraph</a></td>
59+
<td><i>The paragraphs</i></td>
60+
</tr>
3161

3262

3363
</table>
3464

3565
## Paragraph
3666
A model of a paragraph
3767

38-
#### Allowed parameters
39-
<table><tr><td><b>contents</b></td><td>str</td><td><i>Paragraph contents, which make up the <a href="#section">Section</a>s.</i></td></tr>
68+
### Allowed parameters
69+
<table>
70+
<tr>
71+
<td><b>contents</b></td>
72+
<td>str</td>
73+
<td><i>Paragraph contents, which make up the <a href="#section">Section</a>s.</i></td>
74+
</tr>
4075

4176

4277
</table>

‎examples/document.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ class Paragraph(Base):
2121
@modelspec.define
2222
class Section(Base):
2323
"""
24-
A model of a section of the document. Will contain a _Paragraph_ or two
24+
A model of a section of the :class:`Document`. Will contain one :class:`Paragraph` or more
2525
2626
Args:
2727
id: The id of the section

‎examples/document.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Allowed child Data Type Description
2424
=======
2525
Section
2626
=======
27-
A model of a section of the document. Will contain a Paragraph or two
27+
A model of a section of the <a href="#document">Document</a>. Will contain one <a href="#paragraph">Paragraph</a> or more
2828

2929
**Allowed parameters**
3030

‎src/modelspec/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
__version__ = "0.2.1"
1+
__version__ = "0.2.2"
22

33
from .base_types import Base, define, has, field, fields, optional, instance_of, in_
44

‎src/modelspec/base_types.py

Lines changed: 47 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -524,6 +524,35 @@ def _cls_generate_documentation(cls, format: str = MARKDOWN_FORMAT):
524524
rst_url_format = "`%s <%s>`_"
525525

526526
def insert_links(text, format=MARKDOWN_FORMAT):
527+
528+
code_ref = ":code:`"
529+
# print(" > Converting: %s" % text)
530+
text2 = text
531+
while code_ref in text2:
532+
ind = text2.index(code_ref)
533+
ind2 = text2.index("`", ind + len(code_ref) + 1)
534+
pre = text2[0:ind]
535+
ref = text2[ind + len(code_ref) : ind2]
536+
post = text2[ind2 + 1 :]
537+
text2 = f"{pre}<b>{ref}</b>{post}"
538+
# print(" > Converted to: %s" % text2)
539+
text = text2
540+
541+
class_ref = ":class:`"
542+
# print(" > Converting: %s" % text)
543+
text2 = text
544+
while class_ref in text2:
545+
ind = text2.index(class_ref)
546+
ind2 = text2.index("`", ind + len(class_ref) + 1)
547+
pre = text2[0:ind]
548+
ref = text2[ind + len(class_ref) : ind2]
549+
if ref[0] == "~":
550+
ref = ref[1:]
551+
post = text2[ind2 + 1 :]
552+
text2 = f'{pre}<a href="#{ref.lower()}">{ref}</a>{post}'
553+
# print(" > Converted to: %s" % text2)
554+
text = text2
555+
527556
if "_" not in text:
528557
return text
529558
if '"' in text:
@@ -563,7 +592,7 @@ def insert_links(text, format=MARKDOWN_FORMAT):
563592

564593
if len(allowed_fields) > 0:
565594
if format == MARKDOWN_FORMAT:
566-
doc_string += "#### Allowed parameters\n<table>"
595+
doc_string += "### Allowed parameters\n<table>"
567596
if format == RST_FORMAT:
568597
ap = "**Allowed parameters**"
569598
doc_string += "%s\n\n" % (ap)
@@ -586,13 +615,15 @@ def insert_links(text, format=MARKDOWN_FORMAT):
586615
doc_dict[name]["allowed_parameters"][f]["description"] = description
587616

588617
elif format == MARKDOWN_FORMAT:
589-
doc_string += "<tr><td><b>{}</b></td><td>{}</td>".format(
590-
f,
591-
f'<a href="#{type_str.lower()}">{type_str}</a>'
592-
if referencable
593-
else type_str,
618+
doc_string += (
619+
"\n <tr>\n <td><b>{}</b></td>\n <td>{}</td>".format(
620+
f,
621+
f'<a href="#{type_str.lower()}">{type_str}</a>'
622+
if referencable
623+
else type_str,
624+
)
594625
)
595-
doc_string += "<td><i>%s</i></td></tr>\n\n" % (
626+
doc_string += "\n <td><i>%s</i></td>\n </tr>\n\n" % (
596627
insert_links(description)
597628
)
598629

@@ -623,7 +654,7 @@ def insert_links(text, format=MARKDOWN_FORMAT):
623654

624655
if len(allowed_children) > 0:
625656
if format == MARKDOWN_FORMAT:
626-
doc_string += "#### Allowed children\n<table>"
657+
doc_string += "### Allowed children\n<table>"
627658
elif format == RST_FORMAT:
628659
ap = "**Allowed children**"
629660
doc_string += "%s\n\n" % (ap)
@@ -645,13 +676,15 @@ def insert_links(text, format=MARKDOWN_FORMAT):
645676
][0]
646677

647678
elif format == MARKDOWN_FORMAT:
648-
doc_string += "<tr><td><b>{}</b></td><td>{}</td>".format(
649-
c,
650-
f'<a href="#{type_str.lower()}">{type_str}</a>'
651-
if referencable
652-
else type_str,
679+
doc_string += (
680+
"\n <tr>\n <td><b>{}</b></td>\n <td>{}</td>".format(
681+
c,
682+
f'<a href="#{type_str.lower()}">{type_str}</a>'
683+
if referencable
684+
else type_str,
685+
)
653686
)
654-
doc_string += "<td><i>%s</i></td></tr>\n\n" % (
687+
doc_string += "\n <td><i>%s</i></td>\n </tr>\n\n" % (
655688
insert_links(description)
656689
)
657690

0 commit comments

Comments
 (0)