sphinx-examples-as-code 0.3.2__tar.gz → 0.4.0__tar.gz

{sphinx_examples_as_code-0.3.2 → sphinx_examples_as_code-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.3.2
+Version: 0.4.0
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -66,6 +66,7 @@ sphinx_examples_as_code_conf = {
         'py': 'Download Python source code',
         'ipynb': 'Download Jupyter notebook',
     },
+    'include_see_also': True,
 }
 ```
 
@@ -75,6 +76,13 @@ sphinx_examples_as_code_conf = {
   (default). Always offered in that order regardless of how the list is written.
 - `link_labels`: the text of the download link(s) themselves, per format. Set only the
   format(s) you want to change; any left unset keep reading their own default shown above.
+- `include_see_also`: whether "See Also" content is included in the generated file.
+  `True` (default) includes it, in any of its forms: a `.. seealso::` admonition, a bare
+  `.. rubric:: See Also`, a hand-written `See Also` heading, or numpydoc's own "See Also"
+  field (including when it's been reordered outside the Examples section itself, or the
+  Examples section has been hoisted to a heading of its own — a setup some projects use to
+  get "Examples" listed in the page's own navigation). `False` excludes "See Also" content
+  in every one of those forms.
 - `gallery_downloads`: opt-in takeover of
   [sphinx-gallery](https://sphinx-gallery.github.io)'s own per-example downloads.
   `False` (default) leaves sphinx-gallery pages untouched. See
@@ -107,9 +115,14 @@ What happens to the content of an Examples section:
 - `.. code-block:: python` (or `py`) blocks are kept as-is; other languages become
   comments, set off with blank lines on both sides like any other directive.
 - Admonitions (`.. note::`, `.. warning::`, `.. seealso::`, ...) become a `# LABEL:`
-  comment followed by their content as comments. "See Also" is recognized in any of its
-  three forms (`.. seealso::`, a bare `.. rubric:: See Also`, or a hand-written `See
-  Also` heading) and always renders the same way.
+  comment followed by their content as comments, indented one level under the label in
+  `.py` only. "See Also" is recognized in any of its three forms (`.. seealso::`, a bare
+  `.. rubric:: See Also`, or a hand-written `See Also` heading) and always renders the
+  same way.
+- A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
+  line on both sides in either format. A definition list's term stays at the surrounding
+  indent; its definition (the body nested under it) is indented one level further in
+  `.py`, same as an admonition's own content.
 - Cross-references and inline code (`:class:`, `:meth:`, `:func:`, `:attr:`,
   double-backtick literals, ...) keep their display text, wrapped in backticks (e.g.
   ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and
@@ -167,8 +180,7 @@ styles:
 - `.py` uses an RST-style title + underline, one character per level -- the same
   sequence Sphinx's own documentation uses for sections through sub-paragraphs: `=`, `-`,
   `~`, `^`, `"`, `'` for levels 1 through 6.
-- `.ipynb` always uses ATX syntax (`#`, `##`, `###`, ...), since that's a real Markdown
-  heading at any level, whereas an underline only reads as one for the first two.
+- `.ipynb` always uses ATX syntax (`#`, `##`, `###`, ...) at every level.
 
 Two things worth knowing before turning this on:
 

{sphinx_examples_as_code-0.3.2 → sphinx_examples_as_code-0.4.0}/README.md

@@ -39,6 +39,7 @@ sphinx_examples_as_code_conf = {
         'py': 'Download Python source code',
         'ipynb': 'Download Jupyter notebook',
     },
+    'include_see_also': True,
 }
 ```
 
@@ -48,6 +49,13 @@ sphinx_examples_as_code_conf = {
   (default). Always offered in that order regardless of how the list is written.
 - `link_labels`: the text of the download link(s) themselves, per format. Set only the
   format(s) you want to change; any left unset keep reading their own default shown above.
+- `include_see_also`: whether "See Also" content is included in the generated file.
+  `True` (default) includes it, in any of its forms: a `.. seealso::` admonition, a bare
+  `.. rubric:: See Also`, a hand-written `See Also` heading, or numpydoc's own "See Also"
+  field (including when it's been reordered outside the Examples section itself, or the
+  Examples section has been hoisted to a heading of its own — a setup some projects use to
+  get "Examples" listed in the page's own navigation). `False` excludes "See Also" content
+  in every one of those forms.
 - `gallery_downloads`: opt-in takeover of
   [sphinx-gallery](https://sphinx-gallery.github.io)'s own per-example downloads.
   `False` (default) leaves sphinx-gallery pages untouched. See
@@ -80,9 +88,14 @@ What happens to the content of an Examples section:
 - `.. code-block:: python` (or `py`) blocks are kept as-is; other languages become
   comments, set off with blank lines on both sides like any other directive.
 - Admonitions (`.. note::`, `.. warning::`, `.. seealso::`, ...) become a `# LABEL:`
-  comment followed by their content as comments. "See Also" is recognized in any of its
-  three forms (`.. seealso::`, a bare `.. rubric:: See Also`, or a hand-written `See
-  Also` heading) and always renders the same way.
+  comment followed by their content as comments, indented one level under the label in
+  `.py` only. "See Also" is recognized in any of its three forms (`.. seealso::`, a bare
+  `.. rubric:: See Also`, or a hand-written `See Also` heading) and always renders the
+  same way.
+- A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
+  line on both sides in either format. A definition list's term stays at the surrounding
+  indent; its definition (the body nested under it) is indented one level further in
+  `.py`, same as an admonition's own content.
 - Cross-references and inline code (`:class:`, `:meth:`, `:func:`, `:attr:`,
   double-backtick literals, ...) keep their display text, wrapped in backticks (e.g.
   ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and
@@ -140,8 +153,7 @@ styles:
 - `.py` uses an RST-style title + underline, one character per level -- the same
   sequence Sphinx's own documentation uses for sections through sub-paragraphs: `=`, `-`,
   `~`, `^`, `"`, `'` for levels 1 through 6.
-- `.ipynb` always uses ATX syntax (`#`, `##`, `###`, ...), since that's a real Markdown
-  heading at any level, whereas an underline only reads as one for the first two.
+- `.ipynb` always uses ATX syntax (`#`, `##`, `###`, ...) at every level.
 
 Two things worth knowing before turning this on: