Skip to content

Commit affeaaa

Browse files
jorgepilotojorgepiloto
authored
doc: review based on skimming the doc (#83)
2 parents bb4ba30 + 3dfb373 commit affeaaa

File tree

11 files changed

+304
-263
lines changed

11 files changed

+304
-263
lines changed

‎README.rst‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -46,27 +46,32 @@ To install the latest development version of PyWorkbench, use the following comm
4646
cd pyworkbench
4747
pip install -e .
4848
49-
For more information, see `Installation <https://workbench.docs.pyansys.com/version/stable/installation.html>`_ in the PyWorkbench documentation.
49+
For more information, see `Getting started <https://workbench.docs.pyansys.com/version/dev/getting-started.html>`_
50+
in the PyWorkbench documentation.
5051

51-
Documentation
52-
-------------
52+
Documentation and issues
53+
------------------------
5354

5455
Documentation of the latest stable release of PyWorkbench can be found at
55-
`PyWorkbench Documentation <https://workbench.docs.pyansys.com>`_.
56+
`PyWorkbench documentation <https://workbench.docs.pyansys.com>`_.
5657

5758
The documentation has these sections:
5859

59-
- `Installation <https://workbench.docs.pyansys.com/version/stable/installation.html>`_
60-
- `User guide <https://workbench.docs.pyansys.com/version/stable/user_guide.html>`_
61-
- `API reference <https://workbench.docs.pyansys.com/version/stable/api/index.html>`_
62-
- `Contribute <https://workbench.docs.pyansys.com/version/stable/contribute_examples.html>`_
63-
60+
- `Getting started <https://workbench.docs.pyansys.com/version/dev/getting-started.html>`_: Learn
61+
how to install PyWorkbench and connect to Workbench.
62+
- `User guide <https://workbench.docs.pyansys.com/version/dev/user-guide.html>`_: Understand key
63+
concepts and approaches for using PyWorkbench with the Workbench gRPC service.
64+
- `API reference <https://workbench.docs.pyansys.com/version/stable/api/index.html>`_: Understand
65+
how to use Python to interact programmatically with PyWorkbench.
66+
- `Examples <https://workbench.docs.pyansys.com/version/dev/examples.html>`: Explore examples that
67+
show how to use PyWorkbench to create custom applications, automate your existing Workbench
68+
workflows, and integrate with other popular tools in the Python ecosystem.
6469

6570
In the upper right corner of the documentation's title bar, there is an option for switching from
6671
viewing the documentation for the
6772
latest stable release to viewing the documentation for the development version or previously released versions.
6873

69-
On the `PyWorkbench <https://github.com/ansys/pyworkbench/issues>`_
74+
On the `PyWorkbench Issues <https://github.com/ansys/pyworkbench/issues>`_
7075
page, you can create issues to report bugs and request new features. On the
7176
`Discussions <https://discuss.ansys.com/>`_ page on the Ansys Developer portal,
7277
you can post questions, share ideas, and get community feedback.
@@ -75,4 +80,3 @@ If you have general questions about the PyAnsys ecosystem, email
7580
`[email protected] <[email protected]>`_. If your
7681
question is specific to PyWorkbench, ask your
7782
question in an issue as described in the previous paragraph.
78-

‎doc/changelog.d/83.miscellaneous.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Overall review based on skimming the doc

‎doc/source/changelog.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
.. _ref_release_notes:
22

3-
Changelog
4-
#########
3+
Release notes
4+
#############
55

6-
This document contains the release notes for the pyworkbench package.
6+
This document contains the release notes for PyWorkbench.
77

88
.. vale off
99

‎doc/source/examples.rst‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
Examples
22
########
33

4-
This page collects various examples on how to use PyWorkbench.
4+
This section collects examples that show how to use PyWorkbench to create custom applications,
5+
automate your existing Workbench workflows, and integrate with other popular tools in the
6+
Python ecosystem.
57

68
.. grid:: 1
79

@@ -10,4 +12,4 @@ This page collects various examples on how to use PyWorkbench.
1012
:text-align: center
1113
:margin: 2 2 0 0
1214

13-
A collections of examples on how to use PyWorkbench.
15+
Explore both basic and advanced examples for using PyWorkbench.

‎doc/source/getting-started.rst‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,20 @@ To run PyWorkbench, you must have a licensed copy of `Workbench
66

77
.. grid:: 2
88

9-
.. grid-item-card:: Installing PyWorkbench :fab:`python`
9+
.. grid-item-card:: Install PyWorkbench :fab:`python`
1010
:link: getting-started/installing
1111
:link-type: doc
1212

13-
Learn how to download and install PyWorkbench in your development
14-
environment from various official sources including PyPI and official
15-
Ansys repositories.
13+
Learn how to install PyWorkbench in your development
14+
environment from various official sources including PyPI and
15+
the Ansys GitHub repository.
1616

17-
.. grid-item-card:: Connecting to Workbench :fa:`terminal`
17+
.. grid-item-card:: Connect to Workbench :fa:`terminal`
1818
:link: getting-started/connection
1919
:link-type: doc
2020

21-
Learn how to start a new instance of Workbench or connect to an existing
22-
one using PyWorkbench.
21+
Learn how to use PyWorkbench to start a new instance of Workbench
22+
or connect to an existing instance.
2323

2424
.. toctree::
2525
:maxdepth: 3

‎doc/source/getting-started/installing.rst‎

Lines changed: 48 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
1-
Installing PyWorkbench
2-
######################
1+
Install PyWorkbench
2+
###################
33

4-
Installing PyWorkbench is as simple as installing a Python library. However, a running
5-
instance of Workbench is required to use PyWorkbench.
4+
Installing PyWorkbench is as simple as installing any Python library. However, you must
5+
have a running instance of Workbench to use PyWorkbench.
66

7-
User installation
8-
=================
7+
PyWorkbech has two installation modes: user and developer.
98

10-
There are multiple sources for installing the latest stable version of
11-
PyWorkbench. These include ``pip`` and ``GitHub``.
9+
Install in user mode
10+
====================
11+
12+
You can install PyWorkbench in user mode from PyPI sources using ``pip`` or from the
13+
GitHub repository:
1214

1315
.. jinja:: install_guide
1416

@@ -35,8 +37,8 @@ PyWorkbench. These include ``pip`` and ``GitHub``.
3537
3638
python -m pip install git+https://github.com/ansys/pyworkbench.git@{{ version }}
3739
38-
Developer installation
39-
======================
40+
Install in developer mode
41+
=========================
4042

4143
Developer installation is specifically intended for project maintainers. This
4244
specialized installation is tailored to equip developers with the essential
@@ -46,83 +48,82 @@ of technical expertise and familiarity with the project's codebase, rendering it
4648
most suitable for individuals actively engaged in its continuous development and
4749
maintenance.
4850

49-
Start by cloning the repository
51+
#. Cloning the repository:
5052

51-
.. code-block::
53+
.. code-block::
5254
53-
git clone [email protected]:ansys/pyworkbench
55+
git clone [email protected]:ansys/pyworkbench
5456
5557
56-
Move inside the project and create a new Python environment:
58+
#. Move inside the project and create a clean Python environment:
5759

58-
.. tab-set::
60+
.. tab-set::
5961

60-
.. tab-item:: Windows
62+
.. tab-item:: Windows
6163

62-
.. tab-set::
64+
.. tab-set::
6365

64-
.. tab-item:: CMD
66+
.. tab-item:: CMD
6567

66-
.. code-block:: text
68+
.. code-block:: text
6769
68-
py -m venv <venv>
70+
py -m venv <venv>
6971
70-
.. tab-item:: PowerShell
72+
.. tab-item:: PowerShell
7173

72-
.. code-block:: text
74+
.. code-block:: text
7375
74-
py -m venv <venv>
76+
py -m venv <venv>
7577
76-
.. tab-item:: Linux/UNIX
78+
.. tab-item:: Linux/UNIX
7779

78-
.. code-block:: text
80+
.. code-block:: text
7981
80-
python -m venv <venv>
82+
python -m venv <venv>
8183
82-
Activate previous environment:
84+
#. Activate the environment:
8385

84-
.. tab-set::
86+
.. tab-set::
8587

86-
.. tab-item:: Windows
88+
.. tab-item:: Windows
8789

88-
.. tab-set::
90+
.. tab-set::
8991

90-
.. tab-item:: CMD
92+
.. tab-item:: CMD
9193

92-
.. code-block:: text
94+
.. code-block:: text
9395
94-
<venv>\Scripts\activate.bat
96+
<venv>\Scripts\activate.bat
9597
96-
.. tab-item:: PowerShell
98+
.. tab-item:: PowerShell
9799

98-
.. code-block:: text
100+
.. code-block:: text
99101
100-
<venv>\Scripts\Activate.ps1
102+
<venv>\Scripts\Activate.ps1
101103
102-
.. tab-item:: Linux/UNIX
104+
.. tab-item:: Linux/UNIX
103105

104-
.. code-block:: text
106+
.. code-block:: text
105107
106-
source <venv>/bin/activate
108+
source <venv>/bin/activate
107109
108-
Install the project in editable mode. This means that any changes you make to
109-
the package's source code immediately reflect in your project without requiring you
110-
to reinstall it.
110+
#. Install the project in editable mode, which means that any changes you make to
111+
the package's source code is immediately reflected in your project without requiring you
112+
to reinstall it.
111113

112-
.. code-block::
114+
.. code-block::
113115
114-
python -m pip install --editable .
116+
python -m pip install --editable .
115117
116118
117119
Verify your installation
118120
========================
119121

120-
If you have Ansys Workbench installed locally, you can verify your PyWorkbench
121-
installation by starting a Workbench server session on your local computer:
122+
If Ansys Workbench is installed locally, you can verify your PyWorkbench
123+
installation by starting a Workbench server session on your local machine:
122124

123125
.. code-block:: python
124126
125127
from ansys.workbench.core import launch_workbench
126128
127129
workbench = launch_workbench()
128-

‎doc/source/index.rst‎

Lines changed: 16 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,49 +2,45 @@ PyWorkbench documentation |version|
22
###################################
33

44
PyWorkbench provides an environment where you can make use of the capabilities
5-
of various PyAnsys modules for which the Ansys applications have been
6-
integrated with Workbench.
5+
of various PyAnsys modules for Ansys applications that have been integrated
6+
with Workbench.
77

88
.. grid:: 2
99

10-
.. grid-item-card:: Getting started :fa:`person-running`
10+
.. grid-item-card:: Getting started :material-regular:`directions_run`
1111
:link: getting-started
1212
:link-type: doc
1313

14-
Step-by-step guidelines on how to set up your environment to work with
15-
PyWorkbench and verify your installation.
14+
Learn how to install PyWorkbench and connect to Workbench.
1615

17-
.. grid-item-card:: User guide :fa:`book-open-reader`
16+
.. grid-item-card:: User guide :material-regular:`menu_book`
1817
:link: user-guide
1918
:link-type: doc
2019

21-
Learn about the capabilities, features, and key topics in PyWorkbench.
22-
This guide provides useful background information and explanations.
20+
Understand key concepts and approaches for using PyWorkbench with
21+
the Workbench gRPC service.
2322

2423
.. jinja:: main_toctree
2524

2625
{% if build_api or build_examples %}
2726
.. grid:: 2
2827

2928
{% if build_api %}
30-
.. grid-item-card:: API reference :fa:`book-bookmark`
29+
.. grid-item-card:: API reference :material-regular:`bookmark`
3130
:link: api/index
3231
:link-type: doc
3332

34-
A detailed guide describing the PyWorkbench API. This guide documents all the
35-
methods and properties for each interface, class, and
36-
enumerations of each PyWorkbench module.
33+
Understand how to use Python to interact programmatically with PyWorkbench.
3734
{% endif %}
3835

3936
{% if build_examples %}
40-
.. grid-item-card:: Gallery of examples :fa:`laptop-code`
37+
.. grid-item-card:: Examples :material-regular:`play_arrow`
4138
:link: examples
4239
:link-type: doc
4340

44-
Learn how to use PyWorkbench for creating custom applications and automating
45-
your existing Workbench workflows. This guide contains a gallery of examples
46-
showing how to integrate PyWorkbench with other popular tools in the Python
47-
ecosystem.
41+
Explore examples that show how to use PyWorkbench to create custom applications,
42+
automate your existing Workbench workflows, and integrate with other popular tools
43+
in the Python ecosystem.
4844
{% endif %}
4945
{% endif %}
5046

@@ -57,11 +53,10 @@ integrated with Workbench.
5753

5854
getting-started
5955
user-guide
60-
{% if build_examples %}
61-
examples
62-
{% endif %}
6356
{% if build_api %}
6457
api/index
6558
{% endif %}
59+
{% if build_examples %}
60+
examples
61+
{% endif %}
6662
changelog
67-

0 commit comments

Comments
 (0)