source: sasmodels/doc/gentoc.py @ 7e6bc45e

core_shell_microgelsmagnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since 7e6bc45e was 990d8df, checked in by Paul Kienzle <pkienzle@…>, 7 years ago

move polydispersity and resolution docs into sasmodels; write installation instructions

  • Property mode set to 100644
File size: 4.7 KB
Line 
1from __future__ import print_function
2
3import sys
4# make sure sasmodels is on the path
5sys.path.append('..')
6
7from os import mkdir
8from os.path import basename, exists, join as joinpath
9from sasmodels.core import load_model_info
10
11try:
12    from typing import Optional, BinaryIO, List, Dict
13except ImportError:
14    pass
15else:
16    from sasmodels.modelinfo import ModelInfo
17
18TEMPLATE = """\
19..
20    Generated from doc/gentoc.py -- DO NOT EDIT --
21
22.. _%(label)s:
23
24%(bar)s
25%(title)s
26%(bar)s
27
28.. toctree::
29
30"""
31
32MODEL_TOC_PATH = "guide/models"
33
34def _make_category(category_name, label, title, parent=None):
35    # type: (str, str, str, Optional[BinaryIO]) -> BinaryIO
36    file = open(joinpath(MODEL_TOC_PATH, category_name+".rst"), "w")
37    file.write(TEMPLATE%{'label':label, 'title':title, 'bar':'*'*len(title)})
38    if parent:
39        _add_subcategory(category_name, parent)
40    return file
41
42def _add_subcategory(category_name, parent):
43    # type: (str, BinaryIO) -> None
44    parent.write("    %s.rst\n"%category_name)
45
46def _add_model(file, model_name):
47    # type: (IO[str], str) -> None
48    file.write("    ../../model/%s.rst\n"%model_name)
49
50def _maybe_make_category(category, models, cat_files, model_toc):
51    # type: (str, List[str], Dict[str, BinaryIO], BinaryIO) -> None
52    if category not in cat_files:
53        print("Unexpected category %s containing"%category, models, file=sys.stderr)
54        title = category.capitalize()+" Functions"
55        cat_files[category] = _make_category(category, category, title, model_toc)
56
57def generate_toc(model_files):
58    # type: (List[str]) -> None
59    if not model_files:
60        print("gentoc needs a list of model files", file=sys.stderr)
61
62    # find all categories
63    category = {} # type: Dict[str, List[str]]
64    for item in model_files:
65        # assume model is in sasmodels/models/name.py, and ignore the full path
66        model_name = basename(item)[:-3]
67        if model_name.startswith('_'):
68            continue
69        model_info = load_model_info(model_name)
70        if model_info.category is None:
71            print("Missing category for", item, file=sys.stderr)
72        else:
73            category.setdefault(model_info.category, []).append(model_name)
74
75    # Check category names
76    for k, v in category.items():
77        if len(v) == 1:
78            print("Category %s contains only %s"%(k, v[0]), file=sys.stderr)
79
80    # Generate category files for the table of contents.
81    # Initially we had "shape functions" as an additional TOC level, but we
82    # have revised it so that the individual shape categories now go at
83    # the top level.  Judicious rearrangement of comments will make the
84    # "shape functions" level reappear.
85    # We are forcing shape-independent, structure-factor and custom-models
86    # to come at the end of the TOC.  All other categories will come in
87    # alphabetical order before them.
88
89    if not exists(MODEL_TOC_PATH):
90        mkdir(MODEL_TOC_PATH)
91    model_toc = _make_category(
92        'index', 'Models', 'Model Functions')
93    #shape_toc = _make_category(
94    #    'shape',  'Shapes', 'Shape Functions', model_toc)
95    free_toc = _make_category(
96        'shape-independent', 'Shape-independent',
97        'Shape-Independent Functions')
98    struct_toc = _make_category(
99        'structure-factor', 'Structure-factor', 'Structure Factors')
100    #custom_toc = _make_category(
101    #    'custom-models', 'Custom-models', 'Custom Models')
102
103    # remember to top level categories
104    cat_files = {
105        #'shape':shape_toc,
106        'shape':model_toc,
107        'shape-independent':free_toc,
108        'structure-factor': struct_toc,
109        #'custom': custom_toc,
110        }
111
112    # Process the model lists
113    for k, v in sorted(category.items()):
114        if ':' in k:
115            cat, subcat = k.split(':')
116            _maybe_make_category(cat, v, cat_files, model_toc)
117            cat_file = cat_files[cat]
118            label = "-".join((cat, subcat))
119            filename = label
120            title = subcat.capitalize() + " Functions"
121            sub_toc = _make_category(filename, label, title, cat_file)
122            for model in sorted(v):
123                _add_model(sub_toc, model)
124            sub_toc.close()
125        else:
126            _maybe_make_category(k, v, cat_files, model_toc)
127            cat_file = cat_files[k]
128            for model in sorted(v):
129                _add_model(cat_file, model)
130
131    #_add_subcategory('shape', model_toc)
132    _add_subcategory('shape-independent', model_toc)
133    _add_subcategory('structure-factor', model_toc)
134    #_add_subcategory('custom-models', model_toc)
135
136    # Close the top-level category files
137    #model_toc.close()
138    for f in cat_files.values():
139        f.close()
140
141
142if __name__ == "__main__":
143    generate_toc(sys.argv[1:])
Note: See TracBrowser for help on using the repository browser.