FEAT: implement Vale doc style checker

FEAT: implement Vale doc style checker

doc/.vale.ini

@@ -0,0 +1,28 @@
+# Core settings
+# =============
+
+# Location of our `styles`
+StylesPath = "styles"
+
+# The options are `suggestion`, `warning`, or `error` (defaults to “warning”).
+MinAlertLevel = warning
+
+# By default, `code` and `tt` are ignored.
+IgnoredScopes = code, tt
+
+# By default, `script`, `style`, `pre`, and `figure` are ignored.
+SkippedScopes = script, style, pre, figure
+
+# WordTemplate specifies what Vale will consider to be an individual word.
+WordTemplate = \b(?:%s)\b
+
+# List of Packages to be used for our guidelines
+Packages = Google
+
+# Define the Ansys vocabulary
+Vocab = ANSYS
+
+[*.{md,rst}]
+
+# Apply the following styles
+BasedOnStyles = Vale, Google

doc/source/_static/README.md

@@ -1 +1 @@
-Static files will be found here (like images and other assets).
+Static files can be found here (like images and other assets).

doc/source/api/index.rst

@@ -1,7 +1,7 @@
 .. _ref_index_api:
 
 =============
-API Reference
+API reference
 =============
 This section gives an overview of the API of several public PyOptiSLang
 classes, functions, and attributes. Use the search feature or click links to view API documentation.
@@ -14,4 +14,4 @@ classes, functions, and attributes. Use the search feature or click links to vie
    utils
 
 
-
+

doc/source/api/logging.rst

@@ -1,6 +1,6 @@
 Logging
 =======
-To make the logging of events consistent, PyOptislang has a specific
+To make the logging of events consistent, PyOptiSLang has a specific
 logging architecture with global and local logging instances.
 
 For these two types of loggers, the default log message format is:
@@ -34,4 +34,4 @@ Logging API
 .. autosummary::
    :toctree: _autosummary
 
-   OslLogger
+   OslLogger

doc/source/api/optislang.rst

@@ -7,4 +7,4 @@ These classes are specific to the ``optislang`` module:
 .. autosummary::
    :toctree: _autosummary
 
-   Optislang
+   Optislang

doc/source/contributing/index.rst

@@ -12,7 +12,7 @@ contribute to PyOptiSLang.
 
 The following contribution information is specific to PyOptiSLang.
 
-Cloning the PyOptiSLang Repository and Installation
+Cloning the PyOptiSLang repository and installation
 ---------------------------------------------------
 
 .. code::
@@ -23,11 +23,11 @@ Cloning the PyOptiSLang Repository and Installation
     pip install -e .
 
 
-Posting Issues
+Posting issues
 --------------
 Use the `PyOptiSLang Issues <https://github.com/pyansys/pyoptislang/issues>`_
-page to submit questions, report bugs, and request new features. When possible, we
-recommend that you use these issue templates:
+page to submit questions, report bugs, and request new features. When possible, it
+is recommended that you use these issue templates:
 
 * Bug report template
 * Feature request template
@@ -36,7 +36,7 @@ If your issue does not fit into one of these categories, create your own issue.
 
 To reach the project support team, email `[email protected] <[email protected]>`_.
 
-Viewing PyOptiSLang Documentation
+Viewing PyOptiSLang documentation
 ---------------------------------
 Documentation for the latest stable release of PyOptiSLang is hosted at
 `PyOptiSLang Documentation <https://optislangdocs.pyansys.com>`_.
@@ -46,7 +46,7 @@ Documentation for the latest development version, which tracks the
 This version is automatically kept up to date via GitHub actions.
 
 
-Code Style
+Code style
 ----------
 PyOptiSLang follows PEP8 standard as outlined in the `PyAnsys Development Guide
 <https://dev.docs.pyansys.com>`_ and implements style checking using
@@ -68,4 +68,4 @@ This way, it's not possible for you to push code that fails the style checks. Fo
   black....................................................................Passed
   isort....................................................................Passed
   flake8...................................................................Passed
-  codespell................................................................Passed
+  codespell................................................................Passed

doc/source/getting_started/index.rst

@@ -1,14 +1,14 @@
-Getting Started
+Getting started
 ===============
 In order to run PyOptiSLang, user must have access to licensed copy of optiSLang. The first 
-supported supported version of optiSLang is 2023R1. For more information about optiSLang, visit the 
+supported version of optiSLang is 2023R1. For more information about optiSLang, visit the 
 `optiSLang <https://www.ansys.com/products/connect/ansys-optislang>`_ page on the Ansys website.
 
 ************
 Installation
 ************
 
-Python Module
+Python module
 ~~~~~~~~~~~~~
 The ``ansys-optislang-core`` package currently supports python 3.7 through 3.10 on Windows and Linux.
 Install the latest release from `PyPi
@@ -34,7 +34,7 @@ For a local "development" version, install with:
    cd pyoptislang
    pip install -e .
 
-This will allow you to install the PyOptiSLang ``ansys-optislang-core`` module
+This allows you to install the PyOptiSLang ``ansys-optislang-core`` module
 and modify it locally and have the changes reflected in your setup
 after restarting the Python kernel.
 
@@ -52,13 +52,13 @@ For example, on Linux with Python 3.7, unzip it and install it with the followin
     pip install ansys-optislang-core -f wheelhouse --no-index --upgrade --ignore-installed
 
 If you're on Windows with Python 3.9, unzip to a wheelhouse directory and install using the same 
-command as above.
+command as preceding.
 
 Consider installing using a `virtual environment
 <https://docs.python.org/3/library/venv.html>`_.
 
 
-Ansys Software Requirements
+Ansys software requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Ansys optiSLang version >= 2023R1.
 
@@ -73,6 +73,6 @@ Verify installation
     >>> print(osl)
     >>> osl.shutdown()
 
-If you see a response from the server, congratulations!  You're ready
-to get started using OptiSLang as a service.  For details regarding the
-PyOptiSLang interface, see :ref:`ref_user_guide`.
+If you see a response from the server, congratulations, you're ready
+to get started using OptiSLang as a service. For details regarding the
+PyOptiSLang interface, see :ref:`ref_user_guide`.

doc/source/index.rst

@@ -1,4 +1,4 @@
-PyOptiSLang Documentation |version|
+PyOptiSLang documentation |version|
 ===================================
 
 .. toctree::
@@ -29,7 +29,7 @@ and the running optiSLang process (server) is based on the plain TCP/IP technolo
 However, you only need to interact with the Python interface. 
 
 You can use PyOptiSLang to programmatically create, interact with, and control 
-an optiSLang project, create customizable scripts that will speed-up and automate simulations. 
+an optiSLang project, create customizable scripts that can speed-up and automate simulations. 
 
 PyOptiSLang  lets you use optiSLang within a Python environment of your choice 
 in conjunction with other PyAnsys libraries and external Python libraries.
@@ -39,7 +39,7 @@ Features
 Package ``ansys-optislang-core`` provides:
    - Ability to launch optiSLang locally or connect to the remote optiSLang server. For more information, 
      see :ref:`ref_launch`.
-   - Basic commands (e.g., open, save and run project) and queries to obtain information about project. For more 
+   - Basic commands (for example open, save and run project) and queries to obtain information about project. For more 
      information, see :ref:`ref_functions`.
    - Executing Python commands from the optiSLang Python API. For more information, 
      see :ref:`ref_run_python`.
@@ -54,7 +54,7 @@ issues to submit questions, report bugs, and request new features. To reach the
 team, email [email protected].
 
 
-Project Index
+Project index
 *************
 
-* :ref:`genindex`
+* :ref:`genindex`

doc/source/user_guide/functions.rst

@@ -1,9 +1,9 @@
 .. _ref_functions:
 
 Basic usage
-------------------------------
+-----------
 In order to start project, use :func:`start <ansys.optislang.core.optislang.Optislang.start>`
-(example :ref:`ref_simple_calculator` will be used):
+(example :ref:`ref_simple_calculator` can be used):
 
 .. code:: python
     

doc/source/user_guide/index.rst

@@ -1,7 +1,7 @@
 .. _ref_user_guide:
 
 ==========
-User Guide
+User guide
 ==========
 This guide provides a general overview of the basics and usage of the
 PyOptiSLang library.
@@ -16,7 +16,7 @@ PyOptiSLang library.
    troubleshooting
 
 
-PyOptiSLang Basic Overview
+PyOptiSLang basic overview
 --------------------------
 The instance of the :class:`Optislang <ansys.optislang.core.optislang.Optislang>` class 
 within the ``ansys-optislang-core`` library can be used to control and query the optiSLang project.
@@ -57,12 +57,12 @@ and run it using the :func:`start() <ansys.optislang.core.optislang.Optislang.st
     osl.start()
     osl.shutdown()
 
-Currently, the functionality provided by the ``ansys-optislang-core`` library is limited. 
+Currently, the capabilities provided by the ``ansys-optislang-core`` library are limited. 
 However, this can be overcome using the 
 :func:`run_python_script() <ansys.optislang.core.optislang.Optislang.run_python_script>` or
 :func:`run_python_file() <ansys.optislang.core.optislang.Optislang.run_python_file>` functions of 
 the :class:`Optislang <ansys.optislang.core.optislang.Optislang>` class. 
 Both functions provide the ability to execute commands of the ``optiSLang Python API``. 
 Executing commands from ``optiSLang Python API`` is currently the only possibility to create and edit 
-new nodes, parameters etc. These features will be added in the future versions of the ``ansys-optislang-core`` library. 
-For more information, see :ref:`ref_run_python`.
+new nodes, parameters etc. These features may be added in the future versions of the ``ansys-optislang-core`` library. 
+For more information, see :ref:`ref_run_python`.

doc/source/user_guide/launch.rst

@@ -3,7 +3,7 @@
 Initial setup and launching optiSLang
 -------------------------------------
 In order to run, ``ansys.optislang.core`` needs to know the location of the optiSLang.
-Most of the time this can be automatically determined, but non-standard installs will need 
+Most of the time this can be automatically determined, but non-standard installs needs 
 to provide the location of optiSLang. You can start optiSLang by running:
 
 .. code:: python
@@ -22,7 +22,7 @@ List of all automatically detected, supported executables of optiSLang can be ob
     print(utils.find_all_osl_exec())
 
 By default, the newest version is used when launching optiSLang. In order to launch specific version
-from list above, launch :class:`Optislang <ansys.optislang.core.optislang.Optislang>` with parameter 
+from list preceding, launch :class:`Optislang <ansys.optislang.core.optislang.Optislang>` with parameter 
 ``executable`` containing path to desired version:
 
 .. code:: python
@@ -59,4 +59,4 @@ related to the execution of the new optiSLang server are ignored.
      from ansys.optislang.core import Optislang
      osl = Optislang(host = "127.0.0.1", port = 49690)
      print(osl)
-     osl.shutdown()
+     osl.shutdown()

doc/source/user_guide/run_python.rst

@@ -3,8 +3,8 @@
 Executing commands from optiSLang Python API
 -----------------------------------------------
 When optiSLang is active, you can send individual python commands to it as a genuine a
-Python class.  For example, if we wanted to get general information about sensitivity actor, 
-we would call :
+Python class. For example, if you want to get general information about sensitivity actor, 
+you would call:
 
 .. code:: python
 
@@ -20,9 +20,10 @@ we would call :
     is called, new python console is created inside optiSLang, so variables from previous calls 
     won't be available.
 
-For longer scripts, instead of sending string to optiSLang as in the above example, we can instead 
-send path to python script and it's converted to string automatically, example below crates 
-workflow with 2 variable actors and calculator (see example :ref:`ref_simple_calculator`):
+For longer scripts, instead of sending string to optiSLang as in the preceding
+example, it is possible to send path to python script and it's converted to
+string automatically, example below crates workflow with 2 variable actors and
+calculator (see example :ref:`ref_simple_calculator`):
 
 .. code:: python
 
@@ -31,4 +32,4 @@ workflow with 2 variable actors and calculator (see example :ref:`ref_simple_cal
     osl = Optislang()
     path_to_file = examples.get_files('simple_calculator')[0]
     osl.run_python_file(script_path=path_to_file)
-    osl.shutdown()
+    osl.shutdown()

doc/source/user_guide/troubleshooting.rst

@@ -18,7 +18,7 @@ Common issues
 
 Timeout error when launching optiSLang
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Default timeout for launching optiSLang is 20s. This can be increased by parameter ``ini_timeout``
+Default timeout for launching optiSLang is 20 seconds. This can be increased by parameter ``ini_timeout``
 when launching optiSLang:
 
 .. code:: python

doc/styles/.gitignore

@@ -0,0 +1,4 @@
+*
+!Vocab
+!Vocab/**
+!.gitignore

doc/styles/Vocab/ANSYS/accept.txt

@@ -0,0 +1,7 @@
+Ansys
+ansys
+optiSLang
+OptiSLang
+Optislang
+optislang
+PyOptiSLang