Skip to content

Commit f951194

Browse files
dipinknairMaxJPReyPipKatRobPasMue
committed
Modify documentation (#399)
* Removing redundant code blocks * remove sg_execution_times gitignore * - python version correction - image size - checklist modification - table modification * Update doc/source/how-to/setting-up.rst Review feedback Co-authored-by: Maxime Rey <87315832+MaxJPRey@users.noreply.github.com> * Adjust specing of lines * update python supporting versions * Apply suggestions from code review Review from @PipKat Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * Update doc/source/doc-style/formatting-tools.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * Update doc/source/coding-style/formatting-tools.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * Update doc/source/doc-style/formatting-tools.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * Apply suggestions from code review Feedback from @PipKat Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * Update doc/source/how-to/logging.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * Update doc/source/how-to/setting-up.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * Update doc/source/how-to/setting-up.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * Update doc/source/how-to/setting-up.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * Update doc/source/how-to/setting-up.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * Update doc/source/how-to/setting-up.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * Update doc/source/how-to/setting-up.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * vale check * vale feedback --------- Co-authored-by: Maxime Rey <87315832+MaxJPRey@users.noreply.github.com> Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Co-authored-by: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com>
0 parents  commit f951194

File tree

196 files changed

+50311
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

196 files changed

+50311
-0
lines changed

‎.buildinfo‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Sphinx build info version 1
2+
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3+
config: 2a398d12b884ee08c474a23fda76b383
4+
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎.nojekyll‎

Whitespace-only changes.

‎CNAME‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
dev.docs.pyansys.com

‎_downloads/0c5c5e31ce7a7c7f604d78875ac760d9/pyvista_example.ipynb‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"\n\n# Adding a new gallery example\n\nThis example demonstrates how to add a new PyAnsys [Sphinx Gallery](https://sphinx-gallery.github.io/) example as well as being a template that\ncan be used in their creation.\nEach example should have a reference tag/key in the form:\n``.. _<example-name>_example:``.\n\nThe ``.. _`` is necessary. Everything that follows is your reference tag, which\ncan potentially be used within a docstring. As convention, we keep all\nreferences in ``snake_case``.\nThis section should give a brief overview of what the example is about and/or\ndemonstrates. The title should be changed to reflect the topic your example\ncovers.\nNew examples should be added as python scripts to:\n``examples/<index>-<directory-name>/<some-example>.py``\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>Avoid creating new directories unless absolutely necessary. If you *must*\n create a new folder, make sure to add a ``README.txt`` containing a\n reference, a title and a single sentence description of the folder.\n Otherwise the new folder will be ignored by Sphinx.</p></div>\n\nExample file names should be hyphen separated snake case:\n``some-example.py``\nAfter this preamble is complete, the first code block begins. This is where you\ntypically set up your imports.\n"
8+
]
9+
},
10+
{
11+
"cell_type": "code",
12+
"execution_count": null,
13+
"metadata": {
14+
"collapsed": false
15+
},
16+
"outputs": [],
17+
"source": [
18+
"import pyvista as pv"
19+
]
20+
},
21+
{
22+
"cell_type": "markdown",
23+
"metadata": {},
24+
"source": [
25+
"## Section title\n\nCode blocks can be broken up with text \"sections\" which are interpreted as\nrestructured text.\n\nThis will also be translated into a markdown cell in the generated Jupyter\nnotebook or the HTML page.\n\nSections can contain any information you may have regarding the example\nsuch as step-by-step comments or notes regarding motivations etc.\n\nAs in Jupyter notebooks, if a statement is unassigned at the end of a code\nblock, output will be generated and printed to the screen according to its\n``__repr__`` method. Otherwise, you can use ``print()`` to output text.\n\n"
26+
]
27+
},
28+
{
29+
"cell_type": "code",
30+
"execution_count": null,
31+
"metadata": {
32+
"collapsed": false
33+
},
34+
"outputs": [],
35+
"source": [
36+
"# Create a dataset and exercise its repr method\n\ndataset = pv.Sphere()\ndataset"
37+
]
38+
},
39+
{
40+
"cell_type": "markdown",
41+
"metadata": {},
42+
"source": [
43+
"## Plots and images\nIf you use anything that outputs an image (for example,\n:func:`pyvista.Plotter.show`) the resulting image is rendered within the\noutput HTML.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>Unless ``sphinx_gallery_thumbnail_number = <int>`` is included at the top\n of the example script, first figure (this one) is used for the\n gallery thumbnail image.\n\n Also note that this image number uses one based indexing.</p></div>\n\n"
44+
]
45+
},
46+
{
47+
"cell_type": "code",
48+
"execution_count": null,
49+
"metadata": {
50+
"collapsed": false
51+
},
52+
"outputs": [],
53+
"source": [
54+
"dataset.plot(text=\"Example Figure\")"
55+
]
56+
},
57+
{
58+
"cell_type": "markdown",
59+
"metadata": {},
60+
"source": [
61+
"## Caveat - plotter must be within one cell\nIt's not possible for a single :class:`pyvista.Plotter` object across\nmultiple cells because these are closed out automatically at the end of a\ncell.\n\nHere we just exercise the :class:`pyvista.Actor` ``repr`` for demonstrating\nwhy you might want to instantiate a plotter without showing it in the same\ncell.\n\n"
62+
]
63+
},
64+
{
65+
"cell_type": "code",
66+
"execution_count": null,
67+
"metadata": {
68+
"collapsed": false
69+
},
70+
"outputs": [],
71+
"source": [
72+
"pl = pv.Plotter()\nactor = pl.add_mesh(dataset)\nactor"
73+
]
74+
},
75+
{
76+
"cell_type": "markdown",
77+
"metadata": {},
78+
"source": [
79+
"## This cell cannot run the plotter\nThe plotter is already closed by ``sphinx_gallery``.\n\n"
80+
]
81+
},
82+
{
83+
"cell_type": "code",
84+
"execution_count": null,
85+
"metadata": {
86+
"collapsed": false
87+
},
88+
"outputs": [],
89+
"source": [
90+
"# This cannot be run here because the plotter is already closed and would raise\n# an error:\n# >>> pl.show()\n\n# You can, however, close out the plotter or access other attributes.\n\npl.close()"
91+
]
92+
},
93+
{
94+
"cell_type": "markdown",
95+
"metadata": {},
96+
"source": [
97+
"## Making a pull request\nOnce your example is complete and you've verified it builds locally, you can\nmake a pull request (PR).\n\nBranches containing examples should be prefixed with `docs/` as per the branch\nnaming conventions found in out [Contributing Guidelines](https://dev.docs.pyansys.com/how-to/contributing.html#branch-naming-conventions).\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>You only need to create the Python source example (``*.py``). The Jupyter\n notebook and the example HTML are auto-generated via [sphinx-gallery](https://sphinx-gallery.github.io/).</p></div>\n\n"
98+
]
99+
}
100+
],
101+
"metadata": {
102+
"kernelspec": {
103+
"display_name": "Python 3",
104+
"language": "python",
105+
"name": "python3"
106+
},
107+
"language_info": {
108+
"codemirror_mode": {
109+
"name": "ipython",
110+
"version": 3
111+
},
112+
"file_extension": ".py",
113+
"mimetype": "text/x-python",
114+
"name": "python",
115+
"nbconvert_exporter": "python",
116+
"pygments_lexer": "ipython3",
117+
"version": "3.10.13"
118+
}
119+
},
120+
"nbformat": 4,
121+
"nbformat_minor": 0
122+
}

‎_downloads/a1e7d03a60dc93926209dd01b7696263/pyvista_example.py‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
"""
2+
.. _adding_a_new_gallery_example:
3+
4+
Adding a new gallery example
5+
============================
6+
7+
This example demonstrates how to add a new PyAnsys `Sphinx Gallery
8+
<https://sphinx-gallery.github.io/>`_ example as well as being a template that
9+
can be used in their creation.
10+
Each example should have a reference tag/key in the form:
11+
``.. _<example-name>_example:``.
12+
13+
The ``.. _`` is necessary. Everything that follows is your reference tag, which
14+
can potentially be used within a docstring. As convention, we keep all
15+
references in ``snake_case``.
16+
This section should give a brief overview of what the example is about and/or
17+
demonstrates. The title should be changed to reflect the topic your example
18+
covers.
19+
New examples should be added as python scripts to:
20+
``examples/<index>-<directory-name>/<some-example>.py``
21+
22+
.. note::
23+
24+
Avoid creating new directories unless absolutely necessary. If you *must*
25+
create a new folder, make sure to add a ``README.txt`` containing a
26+
reference, a title and a single sentence description of the folder.
27+
Otherwise the new folder will be ignored by Sphinx.
28+
29+
Example file names should be hyphen separated snake case:
30+
``some-example.py``
31+
After this preamble is complete, the first code block begins. This is where you
32+
typically set up your imports.
33+
"""
34+
35+
import pyvista as pv
36+
37+
###############################################################################
38+
# Section title
39+
# ~~~~~~~~~~~~~
40+
#
41+
# Code blocks can be broken up with text "sections" which are interpreted as
42+
# restructured text.
43+
#
44+
# This will also be translated into a markdown cell in the generated Jupyter
45+
# notebook or the HTML page.
46+
#
47+
# Sections can contain any information you may have regarding the example
48+
# such as step-by-step comments or notes regarding motivations etc.
49+
#
50+
# As in Jupyter notebooks, if a statement is unassigned at the end of a code
51+
# block, output will be generated and printed to the screen according to its
52+
# ``__repr__`` method. Otherwise, you can use ``print()`` to output text.
53+
54+
# Create a dataset and exercise its repr method
55+
56+
dataset = pv.Sphere()
57+
dataset
58+
59+
###############################################################################
60+
# Plots and images
61+
# ~~~~~~~~~~~~~~~~
62+
# If you use anything that outputs an image (for example,
63+
# :func:`pyvista.Plotter.show`) the resulting image is rendered within the
64+
# output HTML.
65+
#
66+
# .. note::
67+
#
68+
# Unless ``sphinx_gallery_thumbnail_number = <int>`` is included at the top
69+
# of the example script, first figure (this one) is used for the
70+
# gallery thumbnail image.
71+
#
72+
# Also note that this image number uses one based indexing.
73+
74+
dataset.plot(text="Example Figure")
75+
76+
###############################################################################
77+
# Caveat - plotter must be within one cell
78+
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79+
# It's not possible for a single :class:`pyvista.Plotter` object across
80+
# multiple cells because these are closed out automatically at the end of a
81+
# cell.
82+
#
83+
# Here we just exercise the :class:`pyvista.Actor` ``repr`` for demonstrating
84+
# why you might want to instantiate a plotter without showing it in the same
85+
# cell.
86+
87+
pl = pv.Plotter()
88+
actor = pl.add_mesh(dataset)
89+
actor
90+
91+
###############################################################################
92+
# This cell cannot run the plotter
93+
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94+
# The plotter is already closed by ``sphinx_gallery``.
95+
96+
# This cannot be run here because the plotter is already closed and would raise
97+
# an error:
98+
# >>> pl.show()
99+
100+
# You can, however, close out the plotter or access other attributes.
101+
102+
pl.close()
103+
104+
###############################################################################
105+
# Making a pull request
106+
# ~~~~~~~~~~~~~~~~~~~~~
107+
# Once your example is complete and you've verified it builds locally, you can
108+
# make a pull request (PR).
109+
#
110+
# Branches containing examples should be prefixed with `docs/` as per the branch
111+
# naming conventions found in out `Contributing Guidelines
112+
# <https://dev.docs.pyansys.com/how-to/contributing.html#branch-naming-conventions>`_.
113+
#
114+
# .. note::
115+
#
116+
# You only need to create the Python source example (``*.py``). The Jupyter
117+
# notebook and the example HTML are auto-generated via `sphinx-gallery
118+
# <https://sphinx-gallery.github.io/>`_.

‎_images/architecture_diag.png‎

88.1 KB
Loading

‎_images/github_sections.png‎

9.93 KB
Loading

‎_images/graphviz-063eaec166626f16a0324b89dcf35aff469fd034.png‎

8.15 KB
Loading

‎_images/graphviz-063eaec166626f16a0324b89dcf35aff469fd034.png.map‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
<map id="sphinx&#45;ext&#45;graphviz" name="sphinx&#45;ext&#45;graphviz">
2+
</map>

‎_images/graphviz-3a9db4c83620594cf077b761a9431bd457087125.png‎

13.5 KB
Loading

0 commit comments

Comments
 (0)