sphinx-examples-as-code 0.3.3__tar.gz → 0.4.1__tar.gz

{sphinx_examples_as_code-0.3.3 → sphinx_examples_as_code-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.3.3
+Version: 0.4.1
 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
@@ -108,10 +116,15 @@ What happens to the content of an Examples section:
   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, indented one level under the label in
-  `.py` (not `.ipynb`, where leading whitespace within a paragraph has no visible effect
-  once rendered). "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.
+  `.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 bare `#` instead of a real blank line when
+  that falls inside an admonition or a definition's own body in `.py`, so the whole
+  thing still reads as one unbroken comment block. 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
@@ -169,8 +182,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.3 → sphinx_examples_as_code-0.4.1}/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
@@ -81,10 +89,15 @@ What happens to the content of an Examples section:
   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, indented one level under the label in
-  `.py` (not `.ipynb`, where leading whitespace within a paragraph has no visible effect
-  once rendered). "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.
+  `.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 bare `#` instead of a real blank line when
+  that falls inside an admonition or a definition's own body in `.py`, so the whole
+  thing still reads as one unbroken comment block. 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
@@ -142,8 +155,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: