Skip to content

Commit

Permalink
updating glu to glue in directive+role (#91)
Browse files Browse the repository at this point in the history
  • Loading branch information
@choldgraf
choldgraf authored Mar 24, 2020
1 parent d13261d commit 98bbef6
Show file tree
Hide file tree
Showing 3 changed files with 50 additions and 50 deletions.
82 changes: 41 additions & 41 deletions docs/use/glue.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,13 +70,13 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"You can then insert it into your text like so: {glu:}`my_variable`.\n",
"You can then insert it into your text like so: {glue:}`my_variable`.\n",
"\n",
"That was accomplished with the following code: `` {glu:}`my_variable` ``.\n",
"That was accomplished with the following code: `` {glue:}`my_variable` ``.\n",
"\n",
"### Gluing numbers, plots, and tables\n",
"\n",
"You can glue anything in your notebook and display it later with `{glu:}`. Here\n",
"You can glue anything in your notebook and display it later with `{glue:}`. Here\n",
"we'll show how to glue and paste **numbers and images**. We'll simulate some\n",
"data and run a simple bootstrap on it. We'll hide most of this process below,\n",
"to focus on the glueing part."
Expand Down Expand Up @@ -404,7 +404,7 @@
"\n",
"Once you have glued variables into a notebook, you can then **paste**\n",
"those variables into your text in your book anywhere you like (even on other pages).\n",
"These variables can be pasted using one of the roles or directives in the `glu:` *family*."
"These variables can be pasted using one of the roles or directives in the `glue:` *family*."
]
},
{
Expand All @@ -413,41 +413,41 @@
"source": [
"### The `glu` role/directive\n",
"\n",
"The simplest role and directive are `glu:any`,\n",
"The simplest role and directive are `glue:any`,\n",
"which paste the glued output inline or as a block respectively,\n",
"with no additional formatting.\n",
"Simply add this:\n",
"\n",
"````\n",
"```{glu:} your-key\n",
"```{glue:} your-key\n",
"```\n",
"````\n",
"\n",
"For example, we'll paste the plot we generated above with the following text:\n",
"\n",
"````md\n",
"```{glu:} boot_fig\n",
"```{glue:} boot_fig\n",
"```\n",
"````\n",
"\n",
"Here's how it looks:\n",
"\n",
"```{glu:} boot_fig\n",
"```{glue:} boot_fig\n",
"```\n",
"\n",
"Or we can paste inline objects like so:\n",
"\n",
"\n",
"```md\n",
"Inline text; {glu:}`boot_mean`, and figure; {glu:}`boot_fig`.\n",
"Inline text; {glue:}`boot_mean`, and figure; {glue:}`boot_fig`.\n",
"```\n",
"\n",
"Inline text; {glu:}`boot_mean`, and figure; {glu:}`boot_fig`.\n",
"Inline text; {glue:}`boot_mean`, and figure; {glue:}`boot_fig`.\n",
"\n",
"```{tip}\n",
"We recommend using wider, shorter figures when plotting in-line, with a ratio\n",
"around 6x2. For example, here's is an in-line figure of sorted means\n",
"from our bootstrap: {glu:}`sorted_means_fig`.\n",
"from our bootstrap: {glue:}`sorted_means_fig`.\n",
"It can be used to make a visual point that isn't too complex! For more\n",
"ideas, check out [how sparklines are used](https://en.wikipedia.org/wiki/Sparkline).\n",
"```\n",
Expand All @@ -462,65 +462,65 @@
"source": [
"## Controling the pasted outputs\n",
"\n",
"You can control the pasted outputs by using a sub-command of `{glu:}`. These are called like so:\n",
"`` {glu:subcommand}`key` ``. These subcommands allow you to control more of the look, feel, and\n",
"You can control the pasted outputs by using a sub-command of `{glue:}`. These are called like so:\n",
"`` {glue:subcommand}`key` ``. These subcommands allow you to control more of the look, feel, and\n",
"content of the pasted output.\n",
"\n",
"```{tip}\n",
"When you use `{glu:}` you are actually using a short-hand for `{glu:any}`. This is a\n",
"When you use `{glue:}` you are actually using a short-hand for `{glue:any}`. This is a\n",
"generic command that doesn't make many assumptions about what you are gluing.\n",
"```\n",
"\n",
"### The `glu:text` role\n",
"### The `glue:text` role\n",
"\n",
"\n",
"\n",
"The `glu:text` role, is specific to text outputs.\n",
"The `glue:text` role, is specific to text outputs.\n",
"For example, the following text:\n",
"\n",
"```\n",
"The mean of the bootstrapped distribution was {glu:text}`boot_mean` (95% confidence interval {glu:text}`boot_clo`/{glu:text}`boot_chi`).\n",
"The mean of the bootstrapped distribution was {glue:text}`boot_mean` (95% confidence interval {glue:text}`boot_clo`/{glue:text}`boot_chi`).\n",
"```\n",
"\n",
"Is rendered as: \n",
"The mean of the bootstrapped distribution was {glu:text}`boot_mean` (95% confidence interval {glu:text}`boot_clo`/{glu:text}`boot_chi`)\n",
"The mean of the bootstrapped distribution was {glue:text}`boot_mean` (95% confidence interval {glue:text}`boot_clo`/{glue:text}`boot_chi`)\n",
"\n",
"```{note}\n",
"`glu:text` only works with glued variables that contain a `text/plain` output.\n",
"`glue:text` only works with glued variables that contain a `text/plain` output.\n",
"```\n",
"\n",
"With `glu:text` we can **add formatting to the output**.\n",
"With `glue:text` we can **add formatting to the output**.\n",
"This is particularly useful if you are displaying numbers and\n",
"want to round the results. To add formatting, use this pattern:\n",
"\n",
"* `` {glu:text}`mykey:formatstring` ``\n",
"* `` {glue:text}`mykey:formatstring` ``\n",
"\n",
"For example, the following: ``My rounded mean: {glu:text}`boot_mean:.2f` `` will be rendered like this: My rounded mean: {glu:text}`boot_mean:.2f` (95% CI: {glu:text}`boot_clo:.2f`/{glu:text}`boot_chi:.2f`).\n"
"For example, the following: ``My rounded mean: {glue:text}`boot_mean:.2f` `` will be rendered like this: My rounded mean: {glue:text}`boot_mean:.2f` (95% CI: {glue:text}`boot_clo:.2f`/{glue:text}`boot_chi:.2f`).\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### The `glu:figure` directive\n",
"### The `glue:figure` directive\n",
"\n",
"With `glu:figure` you can apply more formatting to figure like objects,\n",
"With `glue:figure` you can apply more formatting to figure like objects,\n",
"such as giving them a caption and referencable label:\n",
"\n",
"````md\n",
"```{glu:figure} boot_fig\n",
"```{glue:figure} boot_fig\n",
":figwidth: 300px\n",
":name: \"fig-boot\"\n",
"\n",
"This is a **caption**, with an embedded `{glu:text}` element: {glu:text}`boot_mean:.2f`!\n",
"This is a **caption**, with an embedded `{glue:text}` element: {glue:text}`boot_mean:.2f`!\n",
"```\n",
"````\n",
"\n",
"```{glu:figure} boot_fig\n",
"```{glue:figure} boot_fig\n",
":figwidth: 300px\n",
":name: \"fig-boot\"\n",
"\n",
"This is a **caption**, with an embedded `{glu:text}` element: {glu:text}`boot_mean:.2f`!\n",
"This is a **caption**, with an embedded `{glue:text}` element: {glue:text}`boot_mean:.2f`!\n",
"```\n",
"\n",
"```md\n",
Expand All @@ -537,15 +537,15 @@
"Here's a table:\n",
"\n",
"````md\n",
"```{glu:figure} df_tbl\n",
"```{glue:figure} df_tbl\n",
":figwidth: 300px\n",
":name: \"tbl:df\"\n",
"\n",
"A caption for a pandas table.\n",
"```\n",
"\n",
"````\n",
"```{glu:figure} df_tbl\n",
"```{glue:figure} df_tbl\n",
":figwidth: 300px\n",
":name: \"tbl:df\"\n",
"\n",
Expand All @@ -557,9 +557,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### The `glu:math` directive\n",
"### The `glue:math` directive\n",
"\n",
"The `glu:math` directive, is specific to latex math outputs\n",
"The `glue:math` directive, is specific to latex math outputs\n",
"(glued variables that contain a `text/latex` mimetype),\n",
"and works similarly to the [sphinx math directive](https://www.sphinx-doc.org/en/1.8/usage/restructuredtext/directives.html#math).\n",
"For example:"
Expand Down Expand Up @@ -604,7 +604,7 @@
"````md\n",
"Insert the equation here:\n",
"\n",
"```{glu:math} sym_eq\n",
"```{glue:math} sym_eq\n",
":label: eq-sym\n",
"```\n",
"\n",
Expand All @@ -613,14 +613,14 @@
"\n",
"Insert the equation here:\n",
"\n",
"```{glu:math} sym_eq\n",
"```{glue:math} sym_eq\n",
":label: eq-sym\n",
"```\n",
"\n",
"Which we reference as Equation {eq}`eq-sym`.\n",
"\n",
"```{note}\n",
"`glu:math` only works with glued variables that contain a `text/latex` output.\n",
"`glue:math` only works with glued variables that contain a `text/latex` output.\n",
"```"
]
},
Expand All @@ -638,8 +638,8 @@
"shown to users. In this case, you should bundle the notebook with the rest of your\n",
"content pages, but include `orphan:` in the metadata of the notebook.\n",
"\n",
"For example, the following text: `` {glu:}`orphaned_var` was created in {ref}`orphaned-nb` ``.\n",
"Results in: {glu:}`orphaned_var` was created in {ref}`orphaned-nb` \n",
"For example, the following text: `` {glue:}`orphaned_var` was created in {ref}`orphaned-nb` ``.\n",
"Results in: {glue:}`orphaned_var` was created in {ref}`orphaned-nb` \n",
"\n",
"### Pasting into tables\n",
"\n",
Expand All @@ -650,16 +650,16 @@
"````md\n",
"| name | plot | mean | ci |\n",
"|:-------------------------------:|:---------------------------:|---------------------------|---------------------------------------------------|\n",
"| histogram and raw text | {glu:}`boot_fig` | {glu:}`boot_mean` | {glu:}`boot_clo`-{glu:}`boot_chi` |\n",
"| sorted means and formatted text | {glu:}`sorted_means_fig` | {glu:text}`boot_mean:.3f` | {glu:text}`boot_clo:.3f`-{glu:text}`boot_chi:.3f` |\n",
"| histogram and raw text | {glue:}`boot_fig` | {glue:}`boot_mean` | {glue:}`boot_clo`-{glue:}`boot_chi` |\n",
"| sorted means and formatted text | {glue:}`sorted_means_fig` | {glue:text}`boot_mean:.3f` | {glue:text}`boot_clo:.3f`-{glue:text}`boot_chi:.3f` |\n",
"````\n",
"\n",
"Results in:\n",
"\n",
"| name | plot | mean | ci |\n",
"|:-------------------------------:|:---------------------------:|---------------------------|---------------------------------------------------|\n",
"| histogram and raw text | {glu:}`boot_fig` | {glu:}`boot_mean` | {glu:}`boot_clo`-{glu:}`boot_chi` |\n",
"| sorted means and formatted text | {glu:}`sorted_means_fig` | {glu:text}`boot_mean:.3f` | {glu:text}`boot_clo:.3f`-{glu:text}`boot_chi:.3f` |"
"| histogram and raw text | {glue:}`boot_fig` | {glue:}`boot_mean` | {glue:}`boot_clo`-{glue:}`boot_chi` |\n",
"| sorted means and formatted text | {glue:}`sorted_means_fig` | {glue:text}`boot_mean:.3f` | {glue:text}`boot_clo:.3f`-{glue:text}`boot_chi:.3f` |"
]
}
],
Expand Down
2 changes: 1 addition & 1 deletion myst_nb/nb_glue/domain.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,7 @@ def paste_text_role(name, rawtext, text, lineno, inliner, options={}, content=[]
class NbGlueDomain(Domain):
"""A sphinx domain for handling glue data """

name = "glu"
name = "glue"
label = "NotebookGlue"
# data version, bump this when the format of self.data changes
data_version = 0.1
Expand Down
16 changes: 8 additions & 8 deletions tests/notebooks/with_glue.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -190,22 +190,22 @@
"source": [
"## Referencing the figs\n",
"\n",
"{glu:any}`key_text1`, {glu:}`key_plt`\n",
"{glue:any}`key_text1`, {glue:}`key_plt`\n",
"\n",
"```{glu:any} key_df\n",
"```{glue:any} key_df\n",
"```\n",
"\n",
"and {glu:text}`key_text1` inline...\n",
"and {glue:text}`key_text1` inline...\n",
"\n",
"and formatted {glu:text}`key_float:.2f`\n",
"and formatted {glue:text}`key_float:.2f`\n",
"\n",
"```{glu:} key_plt\n",
"```{glue:} key_plt\n",
"```\n",
"\n",
"and {glu:text}`key_undisplayed` inline...\n",
"and {glue:text}`key_undisplayed` inline...\n",
"\n",
"\n",
"```{glu:figure} key_plt\n",
"```{glue:figure} key_plt\n",
":name: abc\n",
"\n",
"A caption....\n",
Expand Down Expand Up @@ -255,7 +255,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"```{glu:math} sym_eq\n",
"```{glue:math} sym_eq\n",
":label: eq-sym\n",
"```"
]
Expand Down

0 comments on commit 98bbef6

Please sign in to comment.