📚 DOCS: Document more config options (#411)

docs/computation/execute.md

@@ -10,8 +10,8 @@ kernelspec:
 MyST-NB can automatically run and cache notebooks contained in your project using [jupyter-cache].
 Notebooks can either be run each time the documentation is built, or cached locally so that re-runs occur only when code cells have changed.
 
-Caching behaviour is controlled with configuration, as outlined in the [configuration section](config/intro).
-See the sections below for a description of each configuration option and its effect.
+Execution and caching behaviour is controlled with configuration at a global or per-file level, as outlined in the [configuration section](config/intro).
+See the sections below for a description of each configuration option and their effect.
 
 (execute/config)=
 

docs/index.md

@@ -69,15 +69,15 @@ Cache execution outputs, for fast re-builds.
 :::
 
 :::{grid-item-card} {material-regular}`preview;2em` Render
-:link: render/output
+:link: render/code-cells
 :link-type: ref
 
 Convert Jupyter execution outputs to embedded content.\
 Insert outputs as variables into your documents.\
 Build single or collections of documents into multiple formats, including HTML websites and PDF books.
 
 +++
-[Learn more »](render/output)
+[Learn more »](render/code-cells)
 :::
 
 ::::

docs/render/format_outputs.md → docs/render/format_code_cells.md

@@ -4,50 +4,44 @@ kernelspec:
   name: python3
 ---
 
-(render/output)=
-# Format code outputs
+(render/code-cells)=
+# Format code cells
 
-(render/output/priority)=
-## Render priority
+Code cell rendering behaviour is controlled with configuration at a global, per-file, or per-cell level, as outlined in the [configuration section](config/intro).
 
-When Jupyter executes a code cell it can produce multiple outputs, and each of these outputs can contain multiple [MIME media types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types), for use by different output formats (like HTML or LaTeX).
+See the sections below for a description of these configuration option and their effect.
 
-MyST-NB stores a base priority dictionary for most of the common [Sphinx builder names](https://www.sphinx-doc.org/en/master/usage/builders/index.html),
-mapping MIME types to a priority number (lower is higher priority):
+(render/input/number)=
+## Number source lines
 
-```{code-cell} ipython3
-:tags: [hide-output]
-
-import yaml
-from myst_nb.core.render import base_render_priority
-print(yaml.dump(base_render_priority()))
-```
+You can control whether the number of source lines is displayed for code cells,
+globally with `nb_number_source_lines = True`, per-file with `number_source_lines` in the notebook metadata, or per-cell with `number_source_lines` in the cell metadata.
+For example:
 
-Items in this dictionary can be overridden by the `nb_mime_priority_overrides` configuration option, in your `conf.py`.
-For example, the following configuration applies in order:
-
-- Sets `text/plain` as the highest priority for `html` output.
-- Disables `image/jpeg` for `latex` output
-- Adds a custom MIME type `customtype` for all builders (`*` applies to all builders)
-
-```python
-nb_mime_priority_overrides = [
-  ('html', 'text/plain', 0),
-  ('latex', 'image/jpeg', None),
-  ('*', 'customtype', 20)
-]
+````markdown
+```{code-cell} ipython3
+---
+mystnb:
+  number_source_lines: true
+---
+a = 1
+b = 2
+c = 1
 ```
+````
 
-```{versionchanged} 0.14.0
-`nb_mime_priority_overrides` replaces `nb_render_priority`
+```{code-cell} ipython3
+---
+mystnb:
+  number_source_lines: true
+---
+a = 1
+b = 2
+c = 1
 ```
 
-:::{seealso}
-[](render/output/cutomise), for a more advanced means of customisation.
-:::
-
 (render/output/stdout-stderr)=
-## stdout and stderr
+## stdout and stderr outputs
 
 (render/output/stderr)=
 ### Remove stdout or stderr
@@ -88,7 +82,7 @@ This can be set to:
 - `"warn"`, `"error"` or `"severe"`: log to sphinx, at a certain level, if any found.
 
 (render/output/group-stderr-stdout)=
-### Group stdout and stderr into single streams
+### Group into single streams
 
 Cells may print multiple things to `stdout` and `stderr`.
 For example, if a cell prints status updates throughout its execution, each of these is often printed to `stdout`.
@@ -104,6 +98,45 @@ This will ensure that all `stderr` and `stdout` outputs are merged into a single
 This also makes cell outputs more deterministic.
 Normally, slight differences in timing may result in different orders of `stderr` and `stdout` in the cell output, while this setting will sort them properly.
 
+(render/output/priority)=
+## Outputs MIME priority
+
+When Jupyter executes a code cell it can produce multiple outputs, and each of these outputs can contain multiple [MIME media types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types), for use by different output formats (like HTML or LaTeX).
+
+MyST-NB stores a base priority dictionary for most of the common [Sphinx builder names](https://www.sphinx-doc.org/en/master/usage/builders/index.html),
+mapping MIME types to a priority number (lower is higher priority):
+
+```{code-cell} ipython3
+:tags: [hide-output]
+
+import yaml
+from myst_nb.core.render import base_render_priority
+print(yaml.dump(base_render_priority()))
+```
+
+Items in this dictionary can be overridden by the `nb_mime_priority_overrides` configuration option, in your `conf.py`.
+For example, the following configuration applies in order:
+
+- Sets `text/plain` as the highest priority for `html` output.
+- Disables `image/jpeg` for `latex` output
+- Adds a custom MIME type `customtype` for all builders (`*` applies to all builders)
+
+```python
+nb_mime_priority_overrides = [
+  ('html', 'text/plain', 0),
+  ('latex', 'image/jpeg', None),
+  ('*', 'customtype', 20)
+]
+```
+
+```{versionchanged} 0.14.0
+`nb_mime_priority_overrides` replaces `nb_render_priority`
+```
+
+:::{seealso}
+[](render/output/cutomise), for a more advanced means of customisation.
+:::
+
 (render/output/images)=
 ## Images and Figures
 
@@ -132,7 +165,6 @@ You can also wrap the output in a [`figure`](https://docutils.sourceforge.io/doc
 ```{code-cell} ipython3
 ---
 mystnb:
-  number_source_lines: true
   image:
     width: 200px
     alt: fun-fish
@@ -152,7 +184,6 @@ Image("images/fun-fish.png")
 ```{code-cell} ipython3
 ---
 mystnb:
-  number_source_lines: true
   image:
     width: 300px
     alt: fun-fish
@@ -170,32 +201,36 @@ Image("images/fun-fish.png")
 
 Now we can link to the image from anywhere in our documentation: [swim to the fish](fun-fish-ref)
 
-You can create figures for any mime outputs:
+You can create figures for any mime outputs, including tables:
 
 ````md
 ```{code-cell} ipython3
 ---
 mystnb:
   figure:
-    align: left
+    align: center
     caption_before: true
-    caption: This is my table caption, aligned left
+    caption: This is my table caption, above the table
 ---
 import pandas
-pandas.DataFrame({"column 1": [1, 2, 3]})
+df = pandas.DataFrame({"column 1": [1, 2, 3]})
+df = df.style.set_table_attributes('class="dataframe align-center"')
+df
 ```
 ````
 
 ```{code-cell} ipython3
 ---
 mystnb:
   figure:
-    align: left
+    align: center
     caption_before: true
-    caption: This is my table caption, aligned left
+    caption: This is my table caption, above the table
 ---
 import pandas
-pandas.DataFrame({"column 1": [1, 2, 3]})
+df = pandas.DataFrame({"column 1": [1, 2, 3]})
+df = df.style.set_table_attributes('class="dataframe align-center"')
+df
 ```
 
 (render/output/markdown)=

docs/render/hiding.md

@@ -17,7 +17,7 @@ package to add a little button that toggles the visibility of content.[^download
 
 ## Hide code cells
 
-You can use **cell tags** to control the content hidden with code cells.
+You can use **cell tags** to control the content hidden with code cells at the cell level.
 Add the following tags to a cell's metadata to control
 what to hide in code cells:
 
@@ -78,8 +78,21 @@ For information on how to hide / toggle markdown content in Sphinx, see either [
 
 ## Remove parts of cells
 
-Sometimes, you want to entirely remove parts of a cell so that it doesn't make it
-into the output at all. To do this, you can use the same tag pattern described above,
+Sometimes, you want to entirely remove parts of a cell so that it doesn't make it into the output at all.
+
+To do this at the global level, use the `nb_remove_code_source` or `nb_remove_code_outputs` configuration options, or at a per-file level, e.g.
+
+```yaml
+---
+mystnb:
+  remove_code_source: true
+  remove_code_outputs: true
+---
+```
+
+See the [configuration section](config/intro) for more details.
+
+At a per-cell level you can use the same tag pattern described above,
 but with the word `remove_` instead of `hide_`. Use the following tags:
 
 * **`remove-input`** tag to remove the cell inputs

docs/render/index.md

@@ -5,7 +5,7 @@ and build output formats.
 
 ```{toctree}
 :maxdepth: 1
-format_outputs
+format_code_cells
 hiding
 glue
 interactive

myst_nb/static/mystnb.css

@@ -101,6 +101,10 @@ div.cell_output table {
     background: rgba(66, 165, 245, 0.2);
   }
 
+/** source code line numbers **/
+span.linenos {
+  opacity: 0.5;
+}
 
 /* Inline text from `paste` operation */