forked from OpenMDAO/Aviary
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request OpenMDAO#520 from crecine/try-glue2
Try glue2
- Loading branch information
Showing
37 changed files
with
1,337 additions
and
218 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,212 @@ | ||
| { | ||
| "cells": [ | ||
| { | ||
| "cell_type": "markdown", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "# DocTAPE\n", | ||
| "\n", | ||
| "DocTAPE (Documentation Testing and Automated Placement of Expressions) is a collection of utility functions (and wrappers for [Glue](https://myst-nb.readthedocs.io/en/latest/render/glue.html)) that are useful\n", | ||
| "for automating the process of building and testing documentation to ensure that documentation doesn't get stale.\n", | ||
| "\n", | ||
| "Our standard practice it to include a comment (`# Testing Cell`) at the begining of code cells as well as make use of the `remove-cell` tag.\n", | ||
| "\n", | ||
| "> \"metadata\": { \"tags\": [ \"remove-cell\" ] },\n", | ||
| "\n", | ||
| "<details><summary>More info about adding cell tags</summary>\n", | ||
| "\n", | ||
| "- [Jupyter Book](https://jupyterbook.org/en/stable/content/metadata.html)\n", | ||
| "- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.vscode-jupyter-cell-tags)\n", | ||
| "</details>\n" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "metadata": { | ||
| "tags": [ | ||
| "remove-cell" | ||
| ] | ||
| }, | ||
| "outputs": [], | ||
| "source": [ | ||
| "# Testing Cell\n" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "metadata": { | ||
| "tags": [ | ||
| "remove-cell" | ||
| ] | ||
| }, | ||
| "outputs": [], | ||
| "source": [ | ||
| "# Testing Cell\n", | ||
| "\n", | ||
| "from aviary.utils import doctape\n", | ||
| "import inspect\n", | ||
| "\n", | ||
| "imported_functions = {k:v for k,v in inspect.getmembers(doctape, inspect.isfunction) if v.__module__ == doctape.__name__}\n", | ||
| "imported_classes = {k:v for k,v in inspect.getmembers(doctape, inspect.isclass) if v.__module__ == doctape.__name__}\n", | ||
| "\n", | ||
| "custom_classes = {\n", | ||
| " \"expected_error\": \"is an execption that can be used in try/except blocks to allow desired errors to pass while still raising unexpected errors.\",\n", | ||
| "}\n", | ||
| "testing_functions = {\n", | ||
| " \"check_value\": \"is a simple function for comparing two values\",\n", | ||
| " \"check_contains\": \"confirms that all the elements of one iterable are contained in the other\",\n", | ||
| " \"check_args\": \"gets the signature of a function and compares it to the arguments you are expecting\",\n", | ||
| " \"run_command_no_file_error\": \"executes a CLI command but won't fail if a FileNotFoundError is raised\",\n", | ||
| "}\n", | ||
| "glue_functions = {\n", | ||
| " \"glue_variable\": \"Glue a variable for later use in markdown cells of notebooks (can auto format for code)\",\n", | ||
| " \"glue_keys\": \"recursively glue all of the keys from a dict of dicts\",\n", | ||
| "}\n", | ||
| "utility_functions = {\n", | ||
| " \"gramatical_list\": \"combines the elements of a list into a string with proper punctuation\",\n", | ||
| " \"get_variable_name\": \"returns the name of the variable passed to the function as a string\",\n", | ||
| " \"get_previous_line\": \"returns the previous line of code as a string\",\n", | ||
| " \"get_attribute_name\": \"gets the name of an object's attribute based on it's value\",\n", | ||
| " \"get_all_keys\": \"recursively get all of the keys from a dict of dicts\",\n", | ||
| " \"get_value\": \"recursively get a value from a dict of dicts\",\n", | ||
| "}\n", | ||
| "\n", | ||
| "doctape.check_value(imported_classes.keys(),custom_classes.keys())\n", | ||
| "doctape.check_value(imported_functions.keys(), {\n", | ||
| " **testing_functions, **glue_functions, **utility_functions}.keys())\n", | ||
| "\n", | ||
| "class_list = ''\n", | ||
| "for key,val in custom_classes.items():\n", | ||
| " doctape.glue_variable(key, md_code=True)\n", | ||
| " class_list += f'- `{key}` {val}\\n'\n", | ||
| "\n", | ||
| "# testing_list = ''\n", | ||
| "# for key,val in testing_functions.items():\n", | ||
| "# testing_list += f'- `{key}` {val}\\n'\n", | ||
| "\n", | ||
| "utility_list = '```{eval-rst}\\n'\n", | ||
| "for key in utility_functions:\n", | ||
| " doctape.glue_variable(key, md_code=True)\n", | ||
| " utility_list += ' '*4+f'.. autofunction:: aviary.utils.doctape.{key}\\n{\" \"*8}:noindex:\\n\\n'\n", | ||
| "utility_list += '```'\n", | ||
| "\n", | ||
| "# testing_list = '```{eval-rst}\\n'\n", | ||
| "# for key in testing_functions:\n", | ||
| "# utils.glue_variable(key, md_code=True)\n", | ||
| "# testing_list += ' '*4+f'.. autofunction:: aviary.utils.doctape.{key}\\n{\" \"*8}:noindex:\\n\\n'\n", | ||
| "# testing_list += '```'\n", | ||
| "\n", | ||
| "# testing_list = '<details>\\n\\n<summary>Function Docs</summary>\\n\\n'\n", | ||
| "testing_list = '```{eval-rst}\\n'\n", | ||
| "for key in testing_functions:\n", | ||
| " doctape.glue_variable(key, md_code=True)\n", | ||
| " testing_list += ' '*4+f'.. autofunction:: aviary.utils.doctape.{key}\\n{\" \"*8}:noindex:\\n\\n'\n", | ||
| "testing_list += '```'\n", | ||
| "# testing_list += '\\n\\n</details>'\n", | ||
| "\n", | ||
| "# glue_list = ''\n", | ||
| "# for key,val in glue_functions.items():\n", | ||
| "# glue_list += f'- `{key}` {key}\\n'\n", | ||
| "\n", | ||
| "# glue_list = ''\n", | ||
| "# for key in glue_functions:\n", | ||
| "# # doc_str = inspect.getdoc(imported_functions[key])\n", | ||
| "# doc_str = imported_functions[key].__doc__.split('\\n')[1]\n", | ||
| "# # doc_str = '\\n'.join([s+' ' for s in imported_functions[key].__doc__.split('\\n')])\n", | ||
| "# print(doc_str)\n", | ||
| "# glue_list += f'- `{key}`: {doc_str}\\n'\n", | ||
| "\n", | ||
| "glue_list = '```{eval-rst}\\n'\n", | ||
| "for key in glue_functions:\n", | ||
| " doctape.glue_variable(key, md_code=True)\n", | ||
| " glue_list += ' '*4+f'.. autofunction:: aviary.utils.doctape.{key}\\n{\" \"*8}:noindex:\\n\\n'\n", | ||
| "glue_list += '```'\n", | ||
| "\n", | ||
| "doctape.glue_variable('class_list', class_list)\n", | ||
| "doctape.glue_variable('utility_list', utility_list)\n", | ||
| "doctape.glue_variable('testing_list', testing_list)\n", | ||
| "doctape.glue_variable('glue_list', glue_list)" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "## Classes\n", | ||
| "```{glue:md} class_list\n", | ||
| ":format: myst\n", | ||
| "```\n", | ||
| "\n", | ||
| "## Testing Functions\n", | ||
| "\n", | ||
| "Functions that raise an error provide the option to specify an error type to use instead of the default. This allows users to change the error type that is raised which can be useful in try/except blocks, especially when combined with the {glue:md}`expected_error` class.\n", | ||
| "\n", | ||
| "```{glue:md} testing_list\n", | ||
| ":format: myst\n", | ||
| "```" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "metadata": { | ||
| "tags": [ | ||
| "remove-cell" | ||
| ] | ||
| }, | ||
| "outputs": [], | ||
| "source": [ | ||
| "# Testing Cell\n", | ||
| "import myst_nb\n", | ||
| "from aviary.utils.doctape import glue_variable\n", | ||
| "\n", | ||
| "glue_variable(myst_nb.__name__)\n", | ||
| "glue_variable(myst_nb.glue.__name__, md_code=True)" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "## Glue Functions\n", | ||
| "\n", | ||
| "The glue functions provide a wrapper for the {glue:md}`myst_nb` {glue:md}`glue` function that provides a simplified interface.\n", | ||
| "\n", | ||
| "```{glue:md} glue_list\n", | ||
| ":format: myst\n", | ||
| "```\n", | ||
| "\n", | ||
| "## Utility Functions\n", | ||
| "\n", | ||
| "Utility functions are provided that the user may find useful for generating or testing their documentation.\n", | ||
| "\n", | ||
| "```{glue:md} utility_list\n", | ||
| ":format: myst\n", | ||
| "```" | ||
| ] | ||
| } | ||
| ], | ||
| "metadata": { | ||
| "kernelspec": { | ||
| "display_name": "latest_env", | ||
| "language": "python", | ||
| "name": "python3" | ||
| }, | ||
| "language_info": { | ||
| "codemirror_mode": { | ||
| "name": "ipython", | ||
| "version": 3 | ||
| }, | ||
| "file_extension": ".py", | ||
| "mimetype": "text/x-python", | ||
| "name": "python", | ||
| "nbconvert_exporter": "python", | ||
| "pygments_lexer": "ipython3", | ||
| "version": "3.10.13" | ||
| } | ||
| }, | ||
| "nbformat": 4, | ||
| "nbformat_minor": 2 | ||
| } |
Oops, something went wrong.