Edits to RST and PY files for rendering documentation (#11)

Co-authored-by: Roberto Pastor Muela <[email protected]>
Co-authored-by: Marina Galvagni <[email protected]>

Author: 3 people

.github/dependabot.yml

@@ -2,12 +2,8 @@ version: 2
 updates:
   - package-ecosystem: "pip" # See documentation for possible values
     directory: "/" # Location of package manifests
-    insecure-external-code-execution: allow
     schedule:
       interval: "daily"
-    labels:
-      - "Maintenance"
-      - "Dependencies"
 
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/ci_cd.yml

@@ -22,7 +22,7 @@ env:
   DOCUMENTATION_CNAME: 'dynamicreporting.docs.pyansys.com'
   MAIN_PYTHON_VERSION: '3.10'
   PACKAGE_NAME: 'ansys-dynamicreporting-core'
-  PACKAGE_NAMESPACE: 'ansys.dynamicreporting'
+  PACKAGE_NAMESPACE: 'ansys.dynamicreporting.core'
 
 jobs:
   style:

.github/workflows/nightly.yml

@@ -8,7 +8,7 @@ on:
 env:
   MAIN_PYTHON_VERSION: '3.10'
   PACKAGE_NAME: 'ansys-dynamicreporting-core'
-  PACKAGE_NAMESPACE: 'ansys.dynamicreporting'
+  PACKAGE_NAMESPACE: 'ansys.dynamicreporting.core'
 
 
 jobs:

.gitignore

@@ -66,4 +66,7 @@ venv/
 *.bak
 
 # VSCode
-.vscode
+.vscode
+
+# Ignore Sphinx files
+doc/_build

README.rst

@@ -1,5 +1,5 @@
-Ansys Dynamic Reporting
-=======================
+PyDynamicReporting
+==================
 
 |pyansys| |python| |pypi| |GH-CI| |bandit| |MIT| |black|
 
@@ -31,41 +31,60 @@ Ansys Dynamic Reporting
    :target: https://github.com/psf/black
    :alt: Black
 
-.. _Ansys Dynamic Reporting: https://nexusdemo.ensight.com/docs/html/Nexus.html
+.. _Nexus: https://nexusdemo.ensight.com/docs/html/Nexus.html
 
 Overview
 --------
-This repository contains the source for ``pydynamicreporting`` - the Python API to
-`Ansys Dynamic Reporting`_. ``pydynamicreporting`` provides an API to connect to an Ansys
-Dynamic Reporting service and manipulate its items and reports. Ansys Dynamic Reporting
-is a service that allows the user to push items of many types (image, text, 3D scenes,
-table, ...) into a database, keep them organized and create dynamic reports from them.
-The ``pydynamicreporting`` module gives the user full access to all these capabilities in
-a natural and pythonic way. To get more information about Ansys Dynamic Reporting,
-please see `the Ansys Dynamic Reporting documentation page`_.
-
-
-.. _the Ansys Dynamic Reporting documentation page: https://nexusdemo.ensight.com/docs/html/Nexus.html
-
+The ``pydynamicreporting`` repository contains the Python client library for
+Ansys Dynamic Reporting, previously documented as `Nexus`_. Ansys Dynamic
+Reporting is a service for pushing items of many types, including images, text,
+3D scenes, and tables, into a database, where you can keep them organized and
+create dynamic reports from them. When you use PyDynamicReporting to connect to
+an instance of Ansys Dynamic Reporting, you have a Pythonic way of accessing all
+capabilities of Ansys Dynamic Reporting.
+
+Documentation and issues
+------------------------
+For comprehensive information on PyDynamicReporting, see the latest release
+`documentation <https://dynamicreporting.docs.pyansys.com>`_.
 
+On the `PyDynamicReporting Issues <https://github.com/ansys/pydynamicreporting/issues>`_
+page, you can create issues to submit questions, report bugs, and request new
+features. This is the best place to post questions and code.
 
 Installation
 ------------
-Currently, ``pydynamicreporting`` is only available on the ANSYS Azure PyPI.
+The ``pydynamicreporting`` package supports Python 3.7 through 3.11 on
+Windows and Linux. It is currently available only on the Ansys private
+repository at `PyAnsysPyPI <https://pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi>`_.
+
+Installing from this private repository requires a PAT (private access
+token). For information on obtaining a PAT, see `Release and publishing
+<https://dev.docs.pyansys.com/dev/how-to/releasing.html#downloading-artifacts>`_
+in the *PyAnsys Developer's Guide*.
 
-Install with:
+To install the package from the Ansys private repository, run this code,
+where ``<PAT>`` is the obtained token:
 
 .. code::
 
    pip install --pre ansys-dynamicreporting-core --index-url=https://<PAT>@pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi/simple/
 
-where `PAT` is private access token. Read how to obtain it `here <https://dev.docs.pyansys.com/dev/how-to/releasing.html#downloading-artifacts>`_.
 
+Once the ``pydynamicreporting`` package is publicly available on GitHub, two modes
+of installation are available:
 
-Development
------------
+- Developer installation
+- User installation
 
-To clone and install in development mode:
+
+The code provided for both installation modes use a `virtual environment
+<https://docs.python.org/3/library/venv.html>`_.
+
+Developer installation
+^^^^^^^^^^^^^^^^^^^^^^
+To clone and install the ``pydynamicreporting`` package in development mode,
+run this code:
 
 .. code::
 
@@ -76,100 +95,111 @@ To clone and install in development mode:
    source venv/bin/activate  # (.\venv\Scripts\activate for Windows shell)
    make install-dev  # install pydynamicreporting in editable mode
 
-This creates an 'editable' installation that lets you
-develop and test pydynamicreporting at the same time.
 
-To build and create a production-like install of pydynamicreporting:
+The preceding code creates an "editable" installation that lets you develop and test
+PyDynamicReporting at the same time.
+
+User installation
+^^^^^^^^^^^^^^^^^
+To build and create a production-like installation for use, run this code:
 
 .. code::
 
    make clean  # clean
    make build   # build
-   # this will replace the editable install done previously. If you don't want to replace,
+   # this replaces the editable installation done previously. If you don't want to replace,
    # switch your virtual environments to test the new install separately.
    make install
    # you can skip the steps above and just do 'make all'
    make smoketest  # test import
 
+
 Pre-commit setup
 ^^^^^^^^^^^^^^^^
 
-``pre-commit`` is a multi-language package manager for pre-commit hooks.
+`pre-commit <https://pre-commit.com/>`_ is a framework for managing and
+maintaining multi-language pre-commit hooks.
 
-To install pre-commit into your git hooks, run:
+To install the ``pre-commit`` package into your Git hooks, run this command:
 
 .. code::
 
    pre-commit install
 
-pre-commit will now run on every commit. Every time you clone a project using pre-commit, this should always be the first thing you do.
 
-If you want to manually run all pre-commit hooks on a repository, run:
+``pre-commit`` now runs on every commit.
+
+Each time you clone a project, installing the ``pre-commit`` package
+should always be the first thing that you do.
+
+If you want to manually run all pre-commit hooks on a repository, run
+this command:
 
 .. code::
 
    pre-commit run --all-files
 
-This will run a bunch of formatters on your source files.
 
-To run individual hooks, use:
+The preceding command runs a bunch of formatters on your source files.
+
+To run an individual hook, obtain the hook ID from the project's
+``.pre-commit-config.yaml`` file and then run this code,
+where ``<hook_id>`` is the obtained ID:
 
 .. code::
 
    pre-commit run <hook_id>
 
-``<hook_id>`` can be obtained from ``.pre-commit-config.yaml``.
-The first time pre-commit runs on a file, it will automatically download, install, and run the hook.
+
+The first time ``pre-commit`` runs on a file, it automatically downloads,
+installs, and runs the hook.
 
 
-Local GitHub actions
+Local GitHub Actions
 ^^^^^^^^^^^^^^^^^^^^
+To run GitHub Actions on your local desktop (recommended), install the
+`act <https://github.com/nektos/act#readme>`_ package.
 
-To simulate GitHub Actions on your local desktop (recommended), install `act <https://github.com/nektos/act#readme>`_.
-To run a job, for example - ``docs`` from ``ci_cd.yml``, use:
+To run a job, such as the ``docs`` job from the ``ci_cd.yml`` file, use
+this command, where ``docs`` is the job name:
 
 .. code::
 
    act -j docs
 
-Deploy and upload steps **must always** be ignored. If not, please add ``if: ${{ !env.ACT }}`` to the workflow step (and commit if required) before running.
 
+Deploy and upload steps **must always** be ignored. If they are not ignored,
+before running GitHub Actions locally, add ``if: ${{ !env.ACT }}`` to the
+workflow step and commit this change if required.
+
+Dependencies
+------------
+To use PyDynamicReporting, you must have a locally installed and licensed copy
+of Ansys 2023 R2 or later.
 
-Usage
------
-The simplest ``pydynamicreporting`` session may be started like this:
+Basic usage
+-----------
+This code shows how to start the simplest PyDynamicReporting session:
 
 .. code:: pycon
 
     >>> import ansys.dynamicreporting.core as adr
-    >>> adr_service = adr.Service(ansys_installation=r"C:\Program Files\ANSYS Inc\v231")
+    >>> adr_service = adr.Service(ansys_installation=r"C:\Program Files\ANSYS Inc\v232")
     >>> ret = adr_service.connect()
     >>> my_img = adr_service.create_item()
     >>> my_img.item_image = "image.png"
     >>> adr_service.visualize_report()
 
-Dependencies
-------------
-You will need a locally installed and licensed copy of Ansys to run Ansys Dynamic Reporting with the
-first supported version being Ansys 2023 R2.
-
-Documentation and Issues
-------------------------
-Please see the latest release `documentation <https://dynamicreporting.docs.pyansys.com>`_
-page for more details.
-
-Please feel free to post issues and other questions at `pydynamicreporting Issues
-<https://github.com/ansys/pydynamicreporting/issues>`_.  This is the best place
-to post questions and code.
 
-License
--------
-``pydynamicreporting`` is licensed under the MIT license.
+License and acknowledgements
+----------------------------
+PyDynamicReporting is licensed under the MIT license.
 
-This module, ``ansys-dynamicreporting-core`` makes no commercial claim over Ansys whatsoever.
-This tool extends the functionality of ``Ansys Dynamic Reporting`` by adding a remote Python
-interface to Ansys Dynamic Reporting without changing the core behavior or license of the original
-software. The use of Ansys Dynamic Reporting through the ``pydynamicreporting``
-interface requires any license that allows the use of stand alone Ansys Dynamic Reporting.
+PyDynamicReporting makes no commercial claim over Ansys whatsoever.
+This library extends the functionality of Ansys Dynamic Reporting by
+adding a Python interface to Ansys Dynamic Reproting without changing
+the core behavior or license of the original software. The use of
+PyDynamicReporting requires a legally licensed copy of an Ansys product
+that supports Ansys Dynamic Reporting.
 
-To get a copy of Ansys, please visit `Ansys <https://www.ansys.com/>`_.
+To get a copy of Ansys, visit the `Ansys <https://www.ansys.com/>`_ website.