Skip to content

Commit 18ba21d

Browse files
clatapiePipKatmike-belcherRobPasMue
authored
maint: documentation review (#44)
Co-authored-by: Kathy Pippert <kathy.pippert@ansys.com> Co-authored-by: Mike Belcher <12882940+mike-belcher@users.noreply.github.com> Co-authored-by: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com> Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com>
1 parent 82c5222 commit 18ba21d

File tree

13 files changed

+400
-369
lines changed

13 files changed

+400
-369
lines changed

‎.github/workflows/cicd.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ jobs:
8989
uses: ansys/actions/doc-build@v5
9090
with:
9191
python-version: ${{ env.MAIN_PYTHON_VERSION }}
92+
dependencies: "texlive-fonts-extra "
9293

9394
package:
9495
name: Package library

‎README.rst‎

Lines changed: 31 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -4,80 +4,45 @@ Ansys Engineering Workflow API
44
Overview
55
--------
66
The Ansys Engineering Workflow API is a Python package that provides a
7-
common interface for interacting with Ansys engineering workflow engines,
8-
such as ModelCenter and OptiSLang.
7+
common interface for interacting with Ansys engineering workflow engines.
98

9+
It is not a standalone package. It is intended to be used in conjunction with
10+
other PyAnsys libraries.
1011

11-
Installation
12-
------------
13-
The ``ansys-engineeringworkflow-api`` package currently supports Python
14-
3.9 through 3.12 on Windows, MacOS and Linux.
12+
Documentation and issues
13+
------------------------
1514

16-
You can install ``ansys-engineeringworkflow-api`` with:
15+
Documentation for the latest stable release of the Ansys Engineering Workflow API is hosted
16+
at `Ansys Engineering Workflow API documentation <https://engineeringworkflow.docs.pyansys.com/version/dev/>`_.
1717

18-
.. code::
18+
The documentation has four sections:
1919

20-
pip install ansys-engineeringworkflow-api
20+
- `Getting started <https://engineeringworkflow.docs.pyansys.com/version/dev/getting_started/index.html>`_: Learn
21+
how to install the Ansys Engineering Workflow API.
22+
- `User guide <https://engineeringworkflow.docs.pyansys.com/version/dev/user_guide/index.html>`_: Understand how to
23+
use the Ansys Engineering Workflow API.
24+
- `API reference <https://rocky.docs.pyansys.com/version/dev/api/index.html>`_: Understand Ansys Engineering Workflow
25+
API endpoints, their capabilities, and how to interact with them programmatically.
26+
- `Contribute <https://engineeringworkflow.docs.pyansys.com/version/dev/contributing/index.html>`_: Learn how to
27+
contribute to the Ansys Engineering Workflow API codebase or documentation.
2128

22-
Alternatively, install the latest version from `ansys-engineeringworkflow-api GitHub
23-
<https://github.com/ansys/ansys-engineeringworkflow-api>`_ via:
29+
In the upper right corner of the documentation's title bar, there is an option
30+
for switching from viewing the documentation for the latest stable release
31+
to viewing the documentation for the development version or previously
32+
released versions.
2433

25-
.. code::
34+
On the `Ansys Engineering Workflow API Issues <https://github.com/ansys/ansys-engineeringworkflow-api/issues>`_
35+
page, you can create issues to report bugs and request new features. On the
36+
`Ansys Engineering Workflow API Discussions <https://github.com/ansys/ansys-engineeringworkflow-api/discussions>`_
37+
page or the `Discussions <https://discuss.ansys.com/>`_ page on the Ansys Developer portal,
38+
you can post questions, share ideas, and get community feedback.
2639

27-
pip install git+https://github.com/ansys/ansys-engineeringworkflow-api
40+
To reach the PyAnsys project support team, email `PyAnsys Core team <pyansys.core@ansys.com>`_.
2841

42+
License
43+
-------
2944

30-
For a local development version, you can install the development
31-
version of the project with:
45+
The Ansys Engineering Workflow API is licensed under the `MIT License <https://github.com/ansys/ansys-engineeringworkflow-api/blob/main/LICENSE>`_.
3246

33-
.. code::
34-
35-
git clone https://github.com/ansys/ansys-engineeringworkflow-api.git
36-
cd ansys-engineeringworkflow-api
37-
pip install -e .
38-
39-
40-
Documentation building
41-
----------------------
42-
43-
Install the required dependencies for building the documentation with this
44-
command:
45-
46-
.. code:: bash
47-
48-
pip install .[doc]
49-
50-
Build and view documentation with the one or more commands for your
51-
operating system:
52-
53-
.. code:: bash
54-
55-
# For Linux and MacOS
56-
make -C doc/ html && your_browser_name doc/build/html/index.html
57-
58-
# For Windows
59-
.\doc\make.bat html
60-
.\doc\build\html\index.html
61-
62-
63-
64-
TODO
65-
----
66-
67-
- [ ] Finish documentation such that pre-commit works as intended
68-
- [ ] Copy (manually, automatically?) main package documentation to README
69-
- [ ] To/FromAPI String
70-
- No extension methods in Python, add to base interface explicitly?
71-
- Our string quoting rules per standard doc (Phoenix.ModelCenter.Common.ModelCenterUtils.EscapeString and UnescapeString)
72-
- [ ] To/From Formatted String
73-
- [ ] Scalar Types
74-
- [ ] Array Types
75-
- Strong typing of ndarray in numpy only added in version of numpy that doesn't support Python 3.7
76-
- [ ] File Types
77-
- Use interface to separate behavior of files from library
78-
- Implement default behavior
79-
- [ ] Clone
80-
- [ ] LinkingRules
81-
- [ ] Variable Factory
82-
- [ ] Variable State
83-
- [ ] Variable Scope
47+
The Ansys Engineering Workflow API makes no commercial claim over Ansys whatsoever.
48+
This library is not intended for standalone use.

‎doc/source/conf.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,13 @@
66

77
from ansys_sphinx_theme import (
88
ansys_favicon,
9+
ansys_logo_white,
10+
ansys_logo_white_cropped,
911
get_autoapi_templates_dir_relative_path,
1012
get_version_match,
13+
latex,
1114
pyansys_logo_black,
15+
watermark,
1216
)
1317

1418
from ansys.engineeringworkflow.api import __version__
@@ -160,6 +164,7 @@
160164
with open("links.rst") as f:
161165
rst_epilog += f.read()
162166

167+
163168
# -- Options for LaTeX output ------------------------------------------------
164169
latex_elements = {}
165170

@@ -175,3 +180,11 @@
175180
"manual",
176181
),
177182
]
183+
184+
# additional logos for the latex coverpage
185+
latex_additional_files = [watermark, ansys_logo_white, ansys_logo_white_cropped]
186+
187+
# change the preamble of latex with customized title page
188+
# variables are the title of pdf, watermark
189+
latex_elements = {"preamble": latex.generate_preamble(html_title)}
190+
sd_fontawesome_latex = True

‎doc/source/contributing/index.rst‎

Lines changed: 48 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -5,37 +5,25 @@ Contribute
55

66
Overall guidance on contributing to a PyAnsys library appears in the
77
`Contributing <dev_guide_contributing_>`_ topic
8-
in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar
9-
with this guide before attempting to contribute to Ansys Engineering Workflow API.
8+
in the *PyAnsys developer's guide*. Ensure that you are thoroughly familiar
9+
with this guide before attempting to contribute to the Ansys Engineering Workflow API.
1010

11-
The following contribution information is specific to Ansys Engineering Workflow API.
11+
The following contribution information is specific to the Ansys Engineering Workflow API.
1212

13-
Installation
14-
------------
13+
Install in developer mode
14+
-------------------------
1515

16-
The ``ansys-engineeringworkflow-api`` package currently supports Python
17-
3.9 through 3.12 on Windows, MacOS, and Linux.
16+
Installing the ``ansys-engineeringworkflow-api`` package in developer mode allows
17+
you to modify the source and enhance it. This package supports Python 3.9 through 3.12
18+
on Windows, MacOS, and Linux.
1819

19-
You can install the ``ansys-engineeringworkflow-api`` package with this command:
20-
21-
.. code::
22-
23-
pip install ansys-engineeringworkflow-api
24-
25-
Alternatively, install the latest version from `ansys-engineeringworkflow-api GitHub
26-
<ansys-engineeringworkflow-api_repo_>`_ with this command:
27-
28-
.. code::
29-
30-
pip install git+https://github.com/ansys/ansys-engineeringworkflow-api
31-
32-
For a local development version, you can create a new virtual environment with this command:
20+
For a local development version, you can create a clean virtual environment with this command:
3321

3422
.. code:: bash
3523
3624
python -m venv .venv
3725
38-
You can then activate the virtual environment with the command appropriate for your operating system:
26+
You can then activate this virtual environment with the command appropriate for your operating system:
3927

4028
.. tab-set::
4129

@@ -61,7 +49,8 @@ You can then activate the virtual environment with the command appropriate for y
6149
.\.venv\Scripts\activate
6250

6351

64-
Next, install the development version of the project with these commands:
52+
Next, install the development version of the ``ansys-engineeringworkflow-api`` package
53+
with these commands:
6554

6655
.. code::
6756
@@ -70,8 +59,8 @@ Next, install the development version of the project with these commands:
7059
pip install -e .
7160
7261
73-
Documentation
74-
-------------
62+
Build documentation
63+
-------------------
7564

7665
Install the required dependencies for the documentation with this command:
7766

@@ -80,7 +69,8 @@ Install the required dependencies for the documentation with this command:
8069
pip install .[doc]
8170
8271
83-
For building documentation, you run the usual rules provided in the Sphinx Makefile for your operating system:
72+
To build documentation, run the usual rules provided in the Sphinx
73+
Makefile for your operating system:
8474

8575
.. tab-set::
8676

@@ -106,26 +96,27 @@ For building documentation, you run the usual rules provided in the Sphinx Makef
10696
.\doc\make.bat html
10797
.\doc\build\html\index.html
10898

109-
11099
Post issues
111100
-----------
112101

113-
Use the `Ansys Engineering Workflow API Issues <ansys-engineeringworkflow-api_issues_>`_ page to submit questions,
114-
report bugs, and request new features. When possible, use these issue
115-
templates:
116-
117-
* Bug report template
118-
* Feature request template
119-
* Documentation issue template
120-
* Example request template
102+
Use the `Ansys Engineering Workflow API Issues <ansys-engineeringworkflow-api_issues_>`_
103+
page to report bugs and request new features.
121104

122-
If your issue does not fit into one of these categories, create your own issue.
105+
When possible, use the issue templates provided. If your issue does not fit into one
106+
of the templates, you can click the link for opening a blank issue.
123107

124108
To reach the PyAnsys support team, email `pyansys.core@ansys.com <pyansys.core@ansys.com>`_.
125109

110+
Verify style and unit tests
111+
---------------------------
126112

127-
Testing
128-
-------
113+
If required, from the command line, you can call commands like `black`_, `isort`_, and `flake8`_.
114+
You can also call unit testing commands like `pytest`_. However, running these commands does not
115+
guarantee that your project is being tested in an isolated environment, which is why you
116+
might consider using `tox`_.
117+
118+
Test
119+
----
129120
You can install the dependencies required for testing with this command:
130121

131122
.. code:: bash
@@ -142,8 +133,8 @@ You can then run the tests via ``pytest`` with this command:
142133
Adhere to code style
143134
--------------------
144135

145-
Ansys Engineering Workflow API follows the PEP8 standard as indicated in the
146-
`PyAnsys Developer's Guide <dev_guide_pyansys_pep8_>`_ and implements style checking using
136+
The Ansys Engineering Workflow API follows the PEP8 standard as indicated in the
137+
`PyAnsys developer's guide <dev_guide_pyansys_pep8_>`_ and implements style checking using
147138
`pre-commit <pre-commit_>`_.
148139

149140
To ensure your code meets minimum code styling standards, run these commands:
@@ -173,3 +164,20 @@ This way, it's not possible for you to push code that fails the style checks:
173164
docformatter.............................................................Passed
174165
codespell................................................................Passed
175166
Validate GitHub Workflows................................................Passed
167+
168+
Distribute
169+
----------
170+
171+
If you would like to create either source or wheel files, start by running this
172+
command to install the building requirements:
173+
174+
.. code:: bash
175+
176+
python -m pip install -e .[doc,tests]
177+
178+
Then, run these commands:
179+
180+
.. code:: bash
181+
182+
python -m build
183+
python -m twine check dist/*

‎doc/source/getting_started/index.rst‎

Lines changed: 17 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,21 @@
1+
.. _getting_started:
2+
13
Getting started
24
===============
35

4-
Installation
5-
------------
6+
The Ansys Engineering Workflow API supports Python 3.9 through 3.12 on Windows,
7+
MacOS, and Linux.
68

7-
Two installation modes of the ``ansys-engineeringworkflow-api`` package are provided: user and developer.
9+
Two installation modes of the ``ansys-engineeringworkflow-api`` package
10+
are provided: user and developer. This section describes how to install
11+
in user mode.
812

9-
Install in user mode
10-
^^^^^^^^^^^^^^^^^^^^
13+
.. note::
14+
If you are interested in contributing to this package, see :ref:`ref_contribute`
15+
for information on installing in developer mode.
16+
17+
Installation
18+
------------
1119

1220
Before installing the ``ansys-engineeringworkflow-api`` package, make sure that you
1321
have the latest version of `pip`_ with this command:
@@ -22,35 +30,9 @@ Then, install the latest ``ansys-engineeringworkflow-api`` package with this com
2230
2331
python -m pip install ansys-engineeringworkflow-api
2432
25-
Install in developer mode
26-
^^^^^^^^^^^^^^^^^^^^^^^^^
27-
28-
Installing the ``ansys-engineeringworkflow-api`` package in developer mode allows
29-
you to modify the source and enhance it.
30-
For more information, see :ref:`ref_contribute`.
31-
32-
Style and testing
33-
-----------------
34-
35-
If required, you can call style commands (such as `black`_, `isort`_,
36-
and `flake8`_) or unit testing commands (such as `pytest`_) from the command line.
37-
However, this does not guarantee that your project is being tested in an isolated
38-
environment, which is why you might consider using `tox`_.
33+
Alternatively, you can install the latest version from the project's `GitHub repository
34+
<https://github.com/ansys/ansys-engineeringworkflow-api>`_ with this command:
3935

36+
.. code::
4037
41-
Distributing
42-
------------
43-
44-
If you would like to create either source or wheel files, start by running this
45-
command to install the building requirements:
46-
47-
.. code:: bash
48-
49-
python -m pip install -e .[doc,tests]
50-
51-
Then, run these commands:
52-
53-
.. code:: bash
54-
55-
python -m build
56-
python -m twine check dist/*
38+
pip install git+https://github.com/ansys/ansys-engineeringworkflow-api

0 commit comments

Comments
 (0)