Write previously extracted docs to disk. Write a docs page for each symbol included in the indices of parser_config to a tree of docs at `output_dir`. Symbols with multiple aliases will have only one page written about them, which is referenced for all aliases. Args: output_dir: Dir
(output_dir,
parser_config,
yaml_toc,
root_title='TensorFlow',
search_hints=True,
site_api_path='')
| 37 | |
| 38 | |
| 39 | def write_docs(output_dir, |
| 40 | parser_config, |
| 41 | yaml_toc, |
| 42 | root_title='TensorFlow', |
| 43 | search_hints=True, |
| 44 | site_api_path=''): |
| 45 | """Write previously extracted docs to disk. |
| 46 | |
| 47 | Write a docs page for each symbol included in the indices of parser_config to |
| 48 | a tree of docs at `output_dir`. |
| 49 | |
| 50 | Symbols with multiple aliases will have only one page written about |
| 51 | them, which is referenced for all aliases. |
| 52 | |
| 53 | Args: |
| 54 | output_dir: Directory to write documentation markdown files to. Will be |
| 55 | created if it doesn't exist. |
| 56 | parser_config: A `parser.ParserConfig` object, containing all the necessary |
| 57 | indices. |
| 58 | yaml_toc: Set to `True` to generate a "_toc.yaml" file. |
| 59 | root_title: The title name for the root level index.md. |
| 60 | search_hints: (bool) include meta-data search hints at the top of each |
| 61 | output file. |
| 62 | site_api_path: The output path relative to the site root. Used in the |
| 63 | `_toc.yaml` and `_redirects.yaml` files. |
| 64 | |
| 65 | Raises: |
| 66 | ValueError: if `output_dir` is not an absolute path |
| 67 | """ |
| 68 | # Make output_dir. |
| 69 | if not os.path.isabs(output_dir): |
| 70 | raise ValueError("'output_dir' must be an absolute path.\n" |
| 71 | " output_dir='%s'" % output_dir) |
| 72 | |
| 73 | if not os.path.exists(output_dir): |
| 74 | os.makedirs(output_dir) |
| 75 | |
| 76 | # These dictionaries are used for table-of-contents generation below |
| 77 | # They will contain, after the for-loop below:: |
| 78 | # - module name(string):classes and functions the module contains(list) |
| 79 | module_children = {} |
| 80 | # - symbol name(string):pathname (string) |
| 81 | symbol_to_file = {} |
| 82 | |
| 83 | # Collect redirects for an api _redirects.yaml file. |
| 84 | redirects = [] |
| 85 | |
| 86 | # Parse and write Markdown pages, resolving cross-links (@{symbol}). |
| 87 | for full_name, py_object in six.iteritems(parser_config.index): |
| 88 | parser_config.reference_resolver.current_doc_full_name = full_name |
| 89 | |
| 90 | if full_name in parser_config.duplicate_of: |
| 91 | continue |
| 92 | |
| 93 | # Methods and some routines are documented only as part of their class. |
| 94 | if not (tf_inspect.ismodule(py_object) or tf_inspect.isclass(py_object) or |
| 95 | parser.is_free_function(py_object, full_name, parser_config.index)): |
| 96 | continue |
no test coverage detected