Class for automatic detection and parsing of API docs to Sphinx-parsable reST format
| 76 | |
| 77 | # Functions and classes |
| 78 | class ApiDocWriter(object): |
| 79 | ''' Class for automatic detection and parsing of API docs |
| 80 | to Sphinx-parsable reST format''' |
| 81 | |
| 82 | # only separating first two levels |
| 83 | rst_section_levels = ['*', '=', '-', '~', '^'] |
| 84 | |
| 85 | def __init__(self, |
| 86 | package_name, |
| 87 | rst_extension='.rst', |
| 88 | package_skip_patterns=None, |
| 89 | module_skip_patterns=None, |
| 90 | names_from__all__=None, |
| 91 | ): |
| 92 | ''' Initialize package for parsing |
| 93 | |
| 94 | Parameters |
| 95 | ---------- |
| 96 | package_name : string |
| 97 | Name of the top-level package. *package_name* must be the |
| 98 | name of an importable package |
| 99 | rst_extension : string, optional |
| 100 | Extension for reST files, default '.rst' |
| 101 | package_skip_patterns : None or sequence of {strings, regexps} |
| 102 | Sequence of strings giving URIs of packages to be excluded |
| 103 | Operates on the package path, starting at (including) the |
| 104 | first dot in the package path, after *package_name* - so, |
| 105 | if *package_name* is ``sphinx``, then ``sphinx.util`` will |
| 106 | result in ``.util`` being passed for earching by these |
| 107 | regexps. If is None, gives default. Default is: |
| 108 | ['\\.tests$'] |
| 109 | module_skip_patterns : None or sequence |
| 110 | Sequence of strings giving URIs of modules to be excluded |
| 111 | Operates on the module name including preceding URI path, |
| 112 | back to the first dot after *package_name*. For example |
| 113 | ``sphinx.util.console`` results in the string to search of |
| 114 | ``.util.console`` |
| 115 | If is None, gives default. Default is: |
| 116 | ['\\.setup$', '\\._'] |
| 117 | names_from__all__ : set, optional |
| 118 | Modules listed in here will be scanned by doing ``from mod import *``, |
| 119 | rather than finding function and class definitions by scanning the |
| 120 | AST. This is intended for API modules which expose things defined in |
| 121 | other files. Modules listed here must define ``__all__`` to avoid |
| 122 | exposing everything they import. |
| 123 | ''' |
| 124 | if package_skip_patterns is None: |
| 125 | package_skip_patterns = ['\\.tests$'] |
| 126 | if module_skip_patterns is None: |
| 127 | module_skip_patterns = ['\\.setup$', '\\._'] |
| 128 | self.package_name = package_name |
| 129 | self.rst_extension = rst_extension |
| 130 | self.package_skip_patterns = package_skip_patterns |
| 131 | self.module_skip_patterns = module_skip_patterns |
| 132 | self.names_from__all__ = names_from__all__ or set() |
| 133 | |
| 134 | def get_package_name(self): |
| 135 | return self._package_name |