From f23c0762093e7d715a00c1cd42e8b27a51b1c8b3 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 10 Mar 2025 09:25:19 +0100 Subject: [PATCH 1/8] docs(contributing): basic layout --- doc/source/cheatsheet/cheatsheet.tex | 23 ++- doc/source/conf.py | 7 + doc/source/contribute.rst | 45 ++++++ doc/source/contribute/developer.rst | 178 ++++++++++++++++++++++++ doc/source/contribute/documentarian.rst | 141 +++++++++++++++++++ doc/source/contribute/user.rst | 119 ++++++++++++++++ doc/source/examples.rst | 2 + doc/source/index.rst | 80 ++++++----- doc/source/links.rst | 37 +++++ 9 files changed, 585 insertions(+), 47 deletions(-) create mode 100644 doc/source/contribute.rst create mode 100644 doc/source/contribute/developer.rst create mode 100644 doc/source/contribute/documentarian.rst create mode 100644 doc/source/contribute/user.rst create mode 100644 doc/source/links.rst diff --git a/doc/source/cheatsheet/cheatsheet.tex b/doc/source/cheatsheet/cheatsheet.tex index f81ed416..a68d9c20 100644 --- a/doc/source/cheatsheet/cheatsheet.tex +++ b/doc/source/cheatsheet/cheatsheet.tex @@ -19,7 +19,7 @@ \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} \fi \usepackage{lmodern} -\ifPDFTeX\else +\ifPDFTeX\else % xetex/luatex font selection \fi % Use upquote if available, for straight quotes in verbatim environments @@ -83,15 +83,17 @@ \makesavenoteenv{longtable} \usepackage{graphicx} \makeatletter -\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi} -\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi} -\makeatother -% Scale images if necessary, so that they will not overflow the page -% margins by default, and it is still possible to overwrite the defaults -% using explicit options in \includegraphics[width, height, ...]{} -\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio} +\newsavebox\pandoc@box +\newcommand*\pandocbounded[1]{% scales image to fit in text height/width + \sbox\pandoc@box{#1}% + \Gscale@div\@tempa{\textheight}{\dimexpr\ht\pandoc@box+\dp\pandoc@box\relax}% + \Gscale@div\@tempb{\linewidth}{\wd\pandoc@box}% + \ifdim\@tempb\p@<\@tempa\p@\let\@tempa\@tempb\fi% select the smaller of both + \ifdim\@tempa\p@<\p@\scalebox{\@tempa}{\usebox\pandoc@box}% + \else\usebox{\pandoc@box}% + \fi% +} % Set default figure placement to htbp -\makeatletter \def\fps@figure{htbp} \makeatother @@ -152,9 +154,6 @@ \@ifpackageloaded{subcaption}{}{\usepackage{subcaption}} \makeatother -\ifLuaTeX - \usepackage{selnolig} % disable illegal ligatures -\fi \usepackage{bookmark} \IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available diff --git a/doc/source/conf.py b/doc/source/conf.py index f42ca2ab..7d2cfe1e 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -126,6 +126,7 @@ "**/ExampleData*", "**/LaunchWorkbench*", "**/ClientWrapper*", + "links.rst", ] # additional logos for the latex coverpage @@ -256,6 +257,7 @@ def get_file_size_in_mb(file_path): jinja_globals = { "SUPPORTED_PYTHON_VERSIONS": ["3.11", "3.12", "3.13"], "SUPPORTED_PLATFORMS": ["windows", "ubuntu"], + "PYWORKBENCH_VERSION": version, } jinja_contexts = { @@ -275,3 +277,8 @@ def get_file_size_in_mb(file_path): "source_hash": get_sha256_from_file(ARTIFACTS_SDIST), }, } + +# Common content for every RST file such us links +rst_epilog = "" +links_filepath = pathlib.Path(__file__).parent.absolute() / "links.rst" +rst_epilog += links_filepath.read_text(encoding="utf-8") diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst new file mode 100644 index 00000000..555434a0 --- /dev/null +++ b/doc/source/contribute.rst @@ -0,0 +1,45 @@ +Contribute +########## + +Thank you for your interest in contributing to PyWorkbench! Contributions are +welcome to make the project better, whether it's fixing bugs, adding new +features, or improving documentation. + +.. important:: + + This project adheres to the `Contributor Covenant Code of Conduct`_. By + participating, you agree to uphold this code. + +Start by selecting your role in the project: + +.. grid:: 1 1 3 3 + + .. grid-item-card:: :fa:`user` User + :link: contribute/user + :link-type: doc + :padding: 2 2 2 2 + + Report bugs, suggesting features, and ask questions. + + .. grid-item-card:: :fa:`book` Documentarian + :link: contribute/documentarian + :link-type: doc + :padding: 2 2 2 2 + + Improve the documentation and write new guides. + + .. grid-item-card:: :fa:`laptop-code` Developer + :link: contribute/developer + :link-type: doc + :padding: 2 2 2 2 + + Fix bugs, add new features, and improve the codebase. + +.. toctree:: + :hidden: + :maxdepth: 3 + :caption: Contribute + + User + Documentarian + Developer diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst new file mode 100644 index 00000000..d45344e7 --- /dev/null +++ b/doc/source/contribute/developer.rst @@ -0,0 +1,178 @@ +Contributing as a developer +########################### + +.. grid:: 1 1 3 3 + + .. grid-item-card:: :fa:`code-fork` Fork the repository + :padding: 2 2 2 2 + :link: fork-the-repository + :link-type: ref + + Learn how to fork the project and get your own copy. + + .. grid-item-card:: :fa:`download` Clone the repository + :padding: 2 2 2 2 + :link: clone-the-repository + :link-type: ref + + Download your own copy in your local machine. + + .. grid-item-card:: :fa:`download` Install for developers + :padding: 2 2 2 2 + :link: install-for-developers + :link-type: ref + + Install the project in editable mode. + + .. grid-item-card:: :fa:`vial-circle-check` Run the tests + :padding: 2 2 2 2 + :link: run-tests + :link-type: ref + + Verify your changes by testing the project. + + +.. _fork-the-repository: + +Fork the repository +=================== + +Forking the repository is the first step to contributing to the project. This +allows you to have your own copy of the project so you can make changes without +affection the main project. Once you have made your changes, you can submit a +pull-request to the main project to have your changes reviewed and merged. + +.. button-link:: https://github.com/ansys/pyworkbench/fork + :color: primary + :align: center + + :fa:`code-fork` Fork this project + +.. note:: + + If you are an Ansys employee, you can skip this step. + +.. _clone-the-repository: + +Clone the repository +==================== + +Make sure you `configure SSH`_ with your GitHub +account. This allows you to clone the repository without having to use tokens +or passwords. Also, make sure you have `git`_ installed in your machine. + +To clone the repository using SSH, run: + +.. code-block:: bash + + git clone git@github.com:ansys/pyworkbench + +.. note:: + + If you are not an Ansys employee, you need to fork the repository and + replace ``ansys`` with your GitHub user name in the ``git clone`` command. + +.. _install-for-developers: + +Install for developers +====================== + +Installing pyworkbench in development mode allows you to perform changes to the code +and see the changes reflected in your environment without having to reinstall +the library every time you make a change. + +Virtual environment +------------------- + +Start by navigating to the project's root directory by running: + +.. code-block:: + + cd pyworkbench + +Then, create a new virtual environment named ``.venv`` to isolate your system's +Python environment by running: + +.. code-block:: text + + python -m venv .venv + +Finally, activate this environment by running: + +.. tab-set:: + + .. tab-item:: Windows + + .. tab-set:: + + .. tab-item:: CMD + + .. code-block:: text + + .venv\Scripts\activate.bat + + .. tab-item:: PowerShell + + .. code-block:: text + + .venv\Scripts\Activate.ps1 + + .. tab-item:: macOS/Linux/UNIX + + .. code-block:: text + + source .venv/bin/activate + +Development mode +---------------- + +Now, install pyworkbench in editable mode by running: + +.. code-block:: text + + python -m pip install --editable . + +Verify the installation by checking the version of the library: + + +.. code-block:: python + + from ansys.workbench.core import __version__ + + + print(f"pyworkbench version is {__version__}") + +.. jinja:: + + .. code-block:: text + + >>> pyworkbench version is {{ PYWORKBENCH_VERSION }} + +Install Tox +----------- + +Once the project is installed, you can install `Tox`_. This is a cross-platform +automation tool. The main advantage of Tox is that it allows you to test your +project in different environments and configurations in a temporary and +isolated Python virtual environment. To install Tox, run: + +.. code-block:: text + + python -m pip install tox + +Finally, verify the installation by listing all the different environments +(automation rules) for pyworkbench: + +.. code-block:: text + + python -m tox list + +.. _run-tests: + +Run the tests +============= + +Once you have made your changes, you can run the tests to verify that your +modifications did not break the project. pyworkbench tests support different markers +to avoid running the whole suite of tests. These markers are associated to a +dedicated `Tox`_ environment. diff --git a/doc/source/contribute/documentarian.rst b/doc/source/contribute/documentarian.rst new file mode 100644 index 00000000..24705650 --- /dev/null +++ b/doc/source/contribute/documentarian.rst @@ -0,0 +1,141 @@ +Contributing as a documentarian +############################### + +.. grid:: 1 1 3 3 + + .. grid-item-card:: :fa:`pencil` Write documentation + :padding: 2 2 2 2 + :link: write-documentation + :link-type: ref + + Explain how to get started, use, and contribute to the project. + + .. grid-item-card:: :fa:`laptop-code` Add a new example + :padding: 2 2 2 2 + :link: write-examples + :link-type: ref + + Showcase the capabilities of PyWorkbench by adding a new example. + + .. grid-item-card:: :fa:`file-code` Build the documentation + :padding: 2 2 2 2 + :link: build-documentation + :link-type: ref + + Render the documentation to see your changes reflected. + +.. _write-documentation: + +Write documentation +=================== + +The documentation generator used in PyWorkbench is `Sphinx`_. Most of the documents +are written in `reStructuredText`_. Some parts of the documentation, like the +:ref:`examples `, use mix of `markdown`_ and Python. If +you are interested in writing examples, see the :ref:`writing examples ` +section. + +The documentation is located in the ``doc/source`` directory. The landing page +is declared in the ``doc/source/index.rst`` file. The rest of the files contain +the main pages of different sections of the documentation. Finally, the +``doc/source/_static/`` folder contains various assets like images, and CSS +files. + +The layout of the ``doc/source`` directory is reflected in the slug of the +online documentation. For example, the +``doc/source/contribute/documentarian.rst`` renders as +``https://workbench.docs.pyansys.com/contribute/documentarian``. + +Thus, if you create a new file, it important to follow these rules: + +- Use lowercase letters for file and directory names +- Use short and descriptive names +- Use hyphens to separate words +- Play smart with the hierarchy of the files and directories + +All files need to be included in a table of contents. No dangling files are +permitted. If a file is not included in the table of contents, Sphinx raises a +warning that makes the build to fail. + +A table of contents can be declared using a directive like this: + +.. code-block:: rst + + .. toctree:: + :hidden: + :maxdepth: 3 + + path-to-file-A + path-to-file-B + path-to-file-C + ... + +The path to the file is relative to the directory where the table of contents +is declared. + +.. _write-examples: + +Write a new example +=================== + +The :ref:`examples ` section of the documentation showcases different +capabilities of PyWorkbench. Each example is a standalone Python script. Despite +being ``*.py`` files, they are written in a mix of `markdown`_ and Python. This +is possible thanks to the `myst-parser`_ Sphinx extension. In addition, these +Python files can be opened as Jupyter Notebooks thanks to the `jupytext`_ +extension. + +Documentarians writing new examples are encouraged to open a new Jupyter Lab +session and write the example as a Jupyter Notebook. This way, the +documentarian can test the code and see the output in real-time. The created +Jupyter Notebook gets stored as a Python file automatically. + +Note that the examples are contained in its own repository, which you can find +in `PyWorkbench examples repository`_. + +Finally, here are some tips for writing examples: + +- Start the example with an explanation of the main topic. For example, if you + are discussing a certain orbital maneuver, explain what that maneuver + entails. Similarly, if an example is centered around satellite coverage, + provide an explanation of what coverage is. Try to use as many relevant + keywords as possible in this section to optimize for Search Engine + Optimization. + +- The second section of the example must be a problem statement. This statement + must include all of the parameters needed in the example, as well as a + description of what the example aims to determine. Write this section in an + imperative form. + +- Include an explanation with each code cell. In a Jupyter notebook, this + entails adding a markdown cell before each code cell. The explanations should + be included before, not after, the corresponding code. + +.. _build-documentation: + +Build the documentation +======================= + +`Tox`_ is used for automating the build of the documentation. There are +different environments for cleaning the build, and building the documentation +in different formats such as HTML. , and running the tests. The following +environments are available: + +The following environments are available: + +.. dropdown:: Documentation environments + :animate: fade-in + :icon: three-bars + + .. list-table:: + :header-rows: 1 + :widths: auto + + * - Environment + - Command + * - doc-style + - python -m tox -e doc-style + * - doc-links + - python -m tox -e doc-links + * - doc-html + - python -m tox -e html diff --git a/doc/source/contribute/user.rst b/doc/source/contribute/user.rst new file mode 100644 index 00000000..97b597d0 --- /dev/null +++ b/doc/source/contribute/user.rst @@ -0,0 +1,119 @@ +Contributing as a user +###################### + +Users can contribute in a variety of ways, such as reporting bugs, requesting +new features, testing in-development features, starting discussions, answering +questions, and sharing their work with the community. + +.. warning:: + + Do not include any proprietary or sensitive information when reporting bugs + or showcasing your work. + +.. grid:: 1 1 3 3 + + .. grid-item-card:: :fa:`bug` Report bugs + :padding: 2 2 2 2 + :link: report-bugs + :link-type: ref + + Found a bug? Report it here. + + .. grid-item-card:: :fa:`lightbulb` Request a new feature + :padding: 2 2 2 2 + :link: request-a-new-feature + :link-type: ref + + Got an idea for a new feature? Share it! + + .. grid-item-card:: :fa:`vial-circle-check` Test a new feature + :padding: 2 2 2 2 + :link: test-a-new-feature + :link-type: ref + + Anxious to try out a new feature? Here's how you can do it. + + .. grid-item-card:: :fa:`comments` Start a discussion + :padding: 2 2 2 2 + :link: start-a-discussion + :link-type: ref + + Want to discuss something? Start a discussion here. + + .. grid-item-card:: :fa:`comment-dots` Answer questions + :padding: 2 2 2 2 + :link: answer-questions + :link-type: ref + + Help others by answering their questions. + + .. grid-item-card:: :fa:`bullhorn` Share your work + :padding: 2 2 2 2 + :link: share-your-work + :link-type: ref + + Share your work with the community. + +.. _report-bugs: + +Report bugs +=========== + +If you encounter a bug or an issue while using the project, please report it. +Your feedback helps to identify problems. + +- Search the `PyWorkbench issues`_ to see if the issue has already been reported. + +- Create a new issue if it hasn’t been reported. + + - Include a clear description of the problem. + - Provide steps to reproduce the issue. + - Mention the version of the project you're using. + - Include screenshots or logs if possible. + +.. _request-a-new-feature: + +Request a new feature +===================== + +Do you have an idea for a new feature or an improvement? Your suggestions are +welcome. You can request a new feature by creating an issue in the `PyWorkbench issues`_ +board. + +.. _test-a-new-feature: + +Test a new feature +================== + +It is possible to test a new feature before it is officially released. To do +so, you can install PyWorkbench from the source code. + +.. _start-a-discussion: + +Start a discussion +================== + +Complex topics may require a discussion. Whether you want to know how to use +PyWorkbench for solving your specific problem or you have a suggestion for a new +feature, a discussion is a good place to start. You can open a new discussion +in the `PyWorkbench discussions`_ section. + +.. _answer-questions: + +Answer questions +================ + +Another great way to contribute is to help others by answering their questions. +Maintain a positive and constructive attitude while answering questions. If you +don't know the answer, you can still help by pointing the person in the right +direction. + +.. _share-your-work: + +Share your work +=============== + +If you have used PyWorkbench to create something interesting, share it with the rest +of the community. You can share your work in the `PyWorkbench discussions`_. Include +a brief description of your work and any relevant links that others may find +useful. diff --git a/doc/source/examples.rst b/doc/source/examples.rst index 135ef2c7..63f2e78f 100644 --- a/doc/source/examples.rst +++ b/doc/source/examples.rst @@ -1,3 +1,5 @@ +.. _examples: + Examples ######## diff --git a/doc/source/index.rst b/doc/source/index.rst index 2daeea40..70363e6a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -5,45 +5,54 @@ PyWorkbench provides an environment where you can make use of the capabilities of various PyAnsys modules for Ansys applications that have been integrated with Workbench. -.. grid:: 2 - - .. grid-item-card:: Getting started :material-regular:`directions_run` - :link: getting-started - :link-type: doc - - Learn how to install PyWorkbench and connect to Workbench. - - .. grid-item-card:: User guide :material-regular:`menu_book` - :link: user-guide - :link-type: doc - - Understand key concepts and approaches for using PyWorkbench with - the Workbench gRPC service. - .. jinja:: main_toctree - {% if build_api or build_examples %} - .. grid:: 2 - - {% if build_api %} - .. grid-item-card:: API reference :material-regular:`bookmark` - :link: api/index - :link-type: doc - - Understand how to use Python to interact programmatically with PyWorkbench. + .. grid:: 1 2 3 3 + :gutter: 1 2 3 3 + :padding: 1 2 3 3 + + .. grid-item-card:: Getting started :material-regular:`directions_run` + :link: getting-started + :link-type: doc + + Learn how to install PyWorkbench and connect to Workbench. + + .. grid-item-card:: User guide :material-regular:`menu_book` + :link: user-guide + :link-type: doc + + Understand key concepts and approaches for using PyWorkbench with + the Workbench gRPC service. + + {% if build_api %} + .. grid-item-card:: API reference :material-regular:`bookmark` + :link: api/index + :link-type: doc + + Understand how to use Python to interact programmatically with PyWorkbench. {% endif %} - - {% if build_examples %} - .. grid-item-card:: Examples :material-regular:`play_arrow` - :link: examples - :link-type: doc - - Explore examples that show how to use PyWorkbench to create custom applications, - automate your existing Workbench workflows, and integrate with other popular tools - in the Python ecosystem. + + {% if build_examples %} + .. grid-item-card:: Examples :material-regular:`play_arrow` + :link: examples + :link-type: doc + + Learn how to use PyWorkbench to create custom applications, + automate your existing Workbench workflows. {% endif %} - {% endif %} - + + .. grid-item-card:: Contribute :fa:`people-group` + :link: contribute + :link-type: doc + + Learn how to contribute to the PyWorkbench project. + + .. grid-item-card:: Artifacts :fa:`download` + :link: artifacts + :link-type: doc + + Download different assets related to PyWorkbench, such as + documentation, package wheelhouse, and related files. .. jinja:: main_toctree @@ -60,4 +69,5 @@ with Workbench. examples {% endif %} changelog + contribute artifacts diff --git a/doc/source/links.rst b/doc/source/links.rst new file mode 100644 index 00000000..694e5860 --- /dev/null +++ b/doc/source/links.rst @@ -0,0 +1,37 @@ +.. PyWorkbench repository links + +.. _PyWorkbench repository: https://github.com/ansys/pyworkbench +.. _PyWorkbench issues: https://github.com/ansys/pyworkbench/issues +.. _PyWorkbench examples repository: https://github.com/ansys/pyworkbench-examples +.. _PyWorkbench discussions: https://github.com/ansys/pyworkbench/discussions +.. _PyWorkbench labels: https://github.com/ansys/pyworkbench/labels + +.. Ansys products + +.. _Workbench: https://www.ansys.com/products/ansys-workbench +.. _PyAnsys: https://docs.pyansys.com + +.. Python documentation + +.. _Python Enhancement Proposals (PEP8) Style Guide: https://peps.python.org/pep-0008/ + +.. Python libraries + +.. _Python: https://www.python.org/ +.. _Jupyter Lab: https://jupyter.org/ +.. _pip: https://pypi.org/project/pip/ +.. _Sphinx: https://www.sphinx-doc.org/en/master/ +.. _reStructuredText: https://docutils.sourceforge.io/rst.html +.. _Markdown: https://www.markdownguide.org/ +.. _myst-parser: https://myst-parser.readthedocs.io/en/latest/ +.. _jupytext: https://jupytext.readthedocs.io/en/latest/ +.. _Tox: https://tox.wiki/en/stable/ + +.. GitHub documentation + +.. _configure SSH: https://docs.github.com/en/authentication/connecting-to-github-with-ssh + +.. Other links + +.. _Contributor Covenant Code of Conduct: https://www.contributor-covenant.org/version/2/1/code_of_conduct/ +.. _git: https://git-scm.com/ From da0774c2dde8c270a7e954edcf0358a7c0b7f13f Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Mon, 10 Mar 2025 08:27:30 +0000 Subject: [PATCH 2/8] chore: adding changelog file 199.documentation.md [dependabot-skip] --- doc/changelog.d/199.documentation.md | 1 + doc/changelog.d/changelog_template.jinja | 21 +++++++++++++-------- 2 files changed, 14 insertions(+), 8 deletions(-) create mode 100644 doc/changelog.d/199.documentation.md diff --git a/doc/changelog.d/199.documentation.md b/doc/changelog.d/199.documentation.md new file mode 100644 index 00000000..99deb2a3 --- /dev/null +++ b/doc/changelog.d/199.documentation.md @@ -0,0 +1 @@ +docs(contributing): basic layout \ No newline at end of file diff --git a/doc/changelog.d/changelog_template.jinja b/doc/changelog.d/changelog_template.jinja index c5fe4e7d..3ca0146b 100644 --- a/doc/changelog.d/changelog_template.jinja +++ b/doc/changelog.d/changelog_template.jinja @@ -1,17 +1,22 @@ {% if sections[""] %} -{% for category, val in definitions.items() if category in sections[""] %} -{{ definitions[category]['name'] }} -{% set underline = '^' * definitions[category]['name']|length %} -{{ underline }} +.. tab-set:: + +{%+ for category, val in definitions.items() if category in sections[""] %} + + .. tab-item:: {{ definitions[category]['name'] }} + + .. list-table:: + :header-rows: 0 + :widths: auto {% for text, values in sections[""][category].items() %} -- {{ text }} {{ values|join(', ') }} -{% endfor %} + * - {{ text }} + - {{ values|join(', ') }} {% endfor %} +{% endfor %} + {% else %} No significant changes. - - {% endif %} From aeefe645b549bb2fea49ebddcc7aacc6dc658b0b Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 10 Mar 2025 09:31:04 +0100 Subject: [PATCH 3/8] fix(tox): test command --- doc/source/contribute/developer.rst | 6 +++++- tox.ini | 13 +++++++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst index d45344e7..b422c222 100644 --- a/doc/source/contribute/developer.rst +++ b/doc/source/contribute/developer.rst @@ -165,7 +165,7 @@ Finally, verify the installation by listing all the different environments .. code-block:: text - python -m tox list + tox list .. _run-tests: @@ -176,3 +176,7 @@ Once you have made your changes, you can run the tests to verify that your modifications did not break the project. pyworkbench tests support different markers to avoid running the whole suite of tests. These markers are associated to a dedicated `Tox`_ environment. + +.. code-block:: text + + tox -e tests diff --git a/tox.ini b/tox.ini index d2a5fcf2..eb4815c0 100644 --- a/tox.ini +++ b/tox.ini @@ -23,6 +23,19 @@ extras = commands = pytest {env:PYTEST_EXTRA_ARGS:} tests +[testenv:tests] +description = Checks for project testing with desired extras +basepython = + {code-style,tests,doc-style,doc,vulnerabilities}: python3 +passenv = + ANSYSLMD_LICENSE_FILE + BUILD_API + BUILD_EXAMPLES +extras = + tests +commands = + pytest {env:PYTEST_EXTRA_ARGS:} tests + [testenv:code-style] description = Checks project code style skip_install = true From 49af9cf3b5bce610a723418ace46d77d86f2ca97 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 10 Mar 2025 09:37:15 +0100 Subject: [PATCH 4/8] fix(style): code --- doc/source/cheatsheet/cheatsheet.tex | 2 +- doc/source/contribute/documentarian.rst | 6 +++--- doc/source/index.rst | 24 ++++++++++++------------ 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/source/cheatsheet/cheatsheet.tex b/doc/source/cheatsheet/cheatsheet.tex index a68d9c20..b451c0c5 100644 --- a/doc/source/cheatsheet/cheatsheet.tex +++ b/doc/source/cheatsheet/cheatsheet.tex @@ -19,7 +19,7 @@ \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} \fi \usepackage{lmodern} -\ifPDFTeX\else +\ifPDFTeX\else % xetex/luatex font selection \fi % Use upquote if available, for straight quotes in verbatim environments diff --git a/doc/source/contribute/documentarian.rst b/doc/source/contribute/documentarian.rst index 24705650..958dfc6e 100644 --- a/doc/source/contribute/documentarian.rst +++ b/doc/source/contribute/documentarian.rst @@ -15,7 +15,7 @@ Contributing as a documentarian :link: write-examples :link-type: ref - Showcase the capabilities of PyWorkbench by adding a new example. + Showcase the capabilities of PyWorkbench by adding a new example. .. grid-item-card:: :fa:`file-code` Build the documentation :padding: 2 2 2 2 @@ -32,7 +32,7 @@ Write documentation The documentation generator used in PyWorkbench is `Sphinx`_. Most of the documents are written in `reStructuredText`_. Some parts of the documentation, like the :ref:`examples `, use mix of `markdown`_ and Python. If -you are interested in writing examples, see the :ref:`writing examples ` +you are interested in writing examples, see the :ref:`writing examples ` section. The documentation is located in the ``doc/source`` directory. The landing page @@ -44,7 +44,7 @@ files. The layout of the ``doc/source`` directory is reflected in the slug of the online documentation. For example, the ``doc/source/contribute/documentarian.rst`` renders as -``https://workbench.docs.pyansys.com/contribute/documentarian``. +``https://workbench.docs.pyansys.com/contribute/documentarian``. Thus, if you create a new file, it important to follow these rules: diff --git a/doc/source/index.rst b/doc/source/index.rst index 70363e6a..36383f8e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -10,47 +10,47 @@ with Workbench. .. grid:: 1 2 3 3 :gutter: 1 2 3 3 :padding: 1 2 3 3 - + .. grid-item-card:: Getting started :material-regular:`directions_run` :link: getting-started :link-type: doc - + Learn how to install PyWorkbench and connect to Workbench. - + .. grid-item-card:: User guide :material-regular:`menu_book` :link: user-guide :link-type: doc - + Understand key concepts and approaches for using PyWorkbench with the Workbench gRPC service. - + {% if build_api %} .. grid-item-card:: API reference :material-regular:`bookmark` :link: api/index :link-type: doc - + Understand how to use Python to interact programmatically with PyWorkbench. {% endif %} - + {% if build_examples %} .. grid-item-card:: Examples :material-regular:`play_arrow` :link: examples :link-type: doc - + Learn how to use PyWorkbench to create custom applications, automate your existing Workbench workflows. {% endif %} - + .. grid-item-card:: Contribute :fa:`people-group` :link: contribute :link-type: doc - + Learn how to contribute to the PyWorkbench project. - + .. grid-item-card:: Artifacts :fa:`download` :link: artifacts :link-type: doc - + Download different assets related to PyWorkbench, such as documentation, package wheelhouse, and related files. From 31a1f6b93df81d8e11c12e126a3d92520452e90e Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 10 Mar 2025 09:38:48 +0100 Subject: [PATCH 5/8] fix(style): doc --- doc/styles/config/vocabularies/ANSYS/accept.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 51569950..0a3a8d73 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -7,3 +7,5 @@ Workbench PyMechanical PyFluent PySherlock +Documentarian +Tox From e06d2c5b569772ae46d89df100f0bdc6e9cca3d8 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 10 Mar 2025 09:42:51 +0100 Subject: [PATCH 6/8] fix(style): doc --- doc/styles/config/vocabularies/ANSYS/accept.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 0a3a8d73..77f6ee8e 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -7,5 +7,5 @@ Workbench PyMechanical PyFluent PySherlock -Documentarian -Tox +(?i)documentarian +(?i)tox From 4d47f24654dac63c9e6ea4f4ce023c3e9fa17f35 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 10 Mar 2025 09:45:20 +0100 Subject: [PATCH 7/8] fix(style): doc --- doc/source/contribute.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst index 555434a0..87df0d64 100644 --- a/doc/source/contribute.rst +++ b/doc/source/contribute.rst @@ -1,7 +1,7 @@ Contribute ########## -Thank you for your interest in contributing to PyWorkbench! Contributions are +Thank you for your interest in contributing to PyWorkbench. Contributions are welcome to make the project better, whether it's fixing bugs, adding new features, or improving documentation. From 8d114af2ce8aa1afb50b1d40e5054965402be913 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Mart=C3=ADnez?= <28702884+jorgepiloto@users.noreply.github.com> Date: Thu, 13 Mar 2025 11:30:29 +0100 Subject: [PATCH 8/8] fix(doc): suggestions Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/contribute.rst | 12 +++--- doc/source/contribute/developer.rst | 52 +++++++++++++------------ doc/source/contribute/documentarian.rst | 52 ++++++++++++------------- doc/source/contribute/user.rst | 20 +++++----- doc/source/index.rst | 2 +- 5 files changed, 69 insertions(+), 69 deletions(-) diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst index 87df0d64..7c044a20 100644 --- a/doc/source/contribute.rst +++ b/doc/source/contribute.rst @@ -1,14 +1,14 @@ Contribute ########## -Thank you for your interest in contributing to PyWorkbench. Contributions are -welcome to make the project better, whether it's fixing bugs, adding new -features, or improving documentation. +Thank you for your interest in contributing to PyWorkbench. Contributions for +making the project better can include fixing bugs, adding new features, and +improving the documentation. .. important:: This project adheres to the `Contributor Covenant Code of Conduct`_. By - participating, you agree to uphold this code. + participating, you agree to uphold this code of conduct. Start by selecting your role in the project: @@ -19,14 +19,14 @@ Start by selecting your role in the project: :link-type: doc :padding: 2 2 2 2 - Report bugs, suggesting features, and ask questions. + Report bugs, suggest features, and ask questions. .. grid-item-card:: :fa:`book` Documentarian :link: contribute/documentarian :link-type: doc :padding: 2 2 2 2 - Improve the documentation and write new guides. + Improve the documentation and write new content. .. grid-item-card:: :fa:`laptop-code` Developer :link: contribute/developer diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst index b422c222..dd296e79 100644 --- a/doc/source/contribute/developer.rst +++ b/doc/source/contribute/developer.rst @@ -1,5 +1,5 @@ -Contributing as a developer -########################### +Contribute as a developer +######################### .. grid:: 1 1 3 3 @@ -8,14 +8,14 @@ Contributing as a developer :link: fork-the-repository :link-type: ref - Learn how to fork the project and get your own copy. + Fork the project to create a copy. .. grid-item-card:: :fa:`download` Clone the repository :padding: 2 2 2 2 :link: clone-the-repository :link-type: ref - Download your own copy in your local machine. + Clone the repository to download the copy to your local machine. .. grid-item-card:: :fa:`download` Install for developers :padding: 2 2 2 2 @@ -29,7 +29,7 @@ Contributing as a developer :link: run-tests :link-type: ref - Verify your changes by testing the project. + Verify your changes to the project by running tests. .. _fork-the-repository: @@ -38,9 +38,9 @@ Fork the repository =================== Forking the repository is the first step to contributing to the project. This -allows you to have your own copy of the project so you can make changes without -affection the main project. Once you have made your changes, you can submit a -pull-request to the main project to have your changes reviewed and merged. +allows you to have your own copy of the project so that you can make changes without +affecting the main project. Once you have made your changes, you can submit a +pull request to the main project to have your changes reviewed and merged. .. button-link:: https://github.com/ansys/pyworkbench/fork :color: primary @@ -57,11 +57,11 @@ pull-request to the main project to have your changes reviewed and merged. Clone the repository ==================== -Make sure you `configure SSH`_ with your GitHub +Make sure that you `configure SSH`_ with your GitHub account. This allows you to clone the repository without having to use tokens -or passwords. Also, make sure you have `git`_ installed in your machine. +or passwords. Also, make sure you have `git`_ installed on your machine. -To clone the repository using SSH, run: +Clone the repository using SSH: .. code-block:: bash @@ -69,35 +69,35 @@ To clone the repository using SSH, run: .. note:: - If you are not an Ansys employee, you need to fork the repository and - replace ``ansys`` with your GitHub user name in the ``git clone`` command. + If you are not an Ansys employee, you must fork the repository and + replace ``ansys`` with your GitHub username in the ``git clone`` command. .. _install-for-developers: Install for developers ====================== -Installing pyworkbench in development mode allows you to perform changes to the code -and see the changes reflected in your environment without having to reinstall +Installing PyWorkbench in development mode lets you change the code +and see these changes reflected in your environment without having to reinstall the library every time you make a change. Virtual environment ------------------- -Start by navigating to the project's root directory by running: +Start by navigating to the project's root directory: .. code-block:: cd pyworkbench Then, create a new virtual environment named ``.venv`` to isolate your system's -Python environment by running: +Python environment: .. code-block:: text python -m venv .venv -Finally, activate this environment by running: +Finally, activate this environment: .. tab-set:: @@ -126,7 +126,7 @@ Finally, activate this environment by running: Development mode ---------------- -Now, install pyworkbench in editable mode by running: +Now, install PyWorkbench in editable mode: .. code-block:: text @@ -154,14 +154,16 @@ Install Tox Once the project is installed, you can install `Tox`_. This is a cross-platform automation tool. The main advantage of Tox is that it allows you to test your project in different environments and configurations in a temporary and -isolated Python virtual environment. To install Tox, run: +isolated Python virtual environment. + +Install Tox: .. code-block:: text python -m pip install tox -Finally, verify the installation by listing all the different environments -(automation rules) for pyworkbench: +Verify the Tox installation by listing all the different environments +(automation rules) for PyWorkbench: .. code-block:: text @@ -173,9 +175,9 @@ Run the tests ============= Once you have made your changes, you can run the tests to verify that your -modifications did not break the project. pyworkbench tests support different markers -to avoid running the whole suite of tests. These markers are associated to a -dedicated `Tox`_ environment. +changes did not break the project. PyWorkbench tests support different markers +to avoid running the whole suite of tests. These markers are associated with a +dedicated Tox environment. .. code-block:: text diff --git a/doc/source/contribute/documentarian.rst b/doc/source/contribute/documentarian.rst index 958dfc6e..93ef6fad 100644 --- a/doc/source/contribute/documentarian.rst +++ b/doc/source/contribute/documentarian.rst @@ -8,14 +8,14 @@ Contributing as a documentarian :link: write-documentation :link-type: ref - Explain how to get started, use, and contribute to the project. + Learn how to get started, use, and contribute to the project. .. grid-item-card:: :fa:`laptop-code` Add a new example :padding: 2 2 2 2 :link: write-examples :link-type: ref - Showcase the capabilities of PyWorkbench by adding a new example. + Write a new example to showcase the capabilities of PyWorkbench. .. grid-item-card:: :fa:`file-code` Build the documentation :padding: 2 2 2 2 @@ -29,33 +29,32 @@ Contributing as a documentarian Write documentation =================== -The documentation generator used in PyWorkbench is `Sphinx`_. Most of the documents -are written in `reStructuredText`_. Some parts of the documentation, like the -:ref:`examples `, use mix of `markdown`_ and Python. If -you are interested in writing examples, see the :ref:`writing examples ` -section. +`Sphinx`_ is the tool used to generate PyWorkbench documentation. You write most of the content +in `ReStructuredText`_ files. However, some of the content, like the +:ref:`examples `, use a mix of `Markdown`_ and Python. If +you are interested in writing examples, see :ref:`writing examples `. The documentation is located in the ``doc/source`` directory. The landing page -is declared in the ``doc/source/index.rst`` file. The rest of the files contain -the main pages of different sections of the documentation. Finally, the +is declared in the ``doc/source/index.rst`` file. The subdirectories contain +the pages of different documentation sections. Finally, the ``doc/source/_static/`` folder contains various assets like images, and CSS files. -The layout of the ``doc/source`` directory is reflected in the slug of the -online documentation. For example, the -``doc/source/contribute/documentarian.rst`` renders as -``https://workbench.docs.pyansys.com/contribute/documentarian``. +The layout of the ``doc/source`` directory is reflected in the URLs of the +online documentation pages. For example, the +``doc/source/contribute/documentarian.rst``file renders as +``https://workbench.docs.pyansys.com/contribute/documentarian`` URL. -Thus, if you create a new file, it important to follow these rules: +Thus, if you create a file, it important to follow these rules: -- Use lowercase letters for file and directory names -- Use short and descriptive names -- Use hyphens to separate words -- Play smart with the hierarchy of the files and directories +- Use lowercase letters for file and directory names. +- Use short and descriptive names. +- Use hyphens to separate words. +- Play smart with the hierarchy of the files and directories. -All files need to be included in a table of contents. No dangling files are +You must include all files in a table of contents. No orphan files are permitted. If a file is not included in the table of contents, Sphinx raises a -warning that makes the build to fail. +warning that causes the build to fail. A table of contents can be declared using a directive like this: @@ -80,14 +79,14 @@ Write a new example The :ref:`examples ` section of the documentation showcases different capabilities of PyWorkbench. Each example is a standalone Python script. Despite -being ``*.py`` files, they are written in a mix of `markdown`_ and Python. This +being PY files, they are written in a mix of `Markdown`_ and Python. This is possible thanks to the `myst-parser`_ Sphinx extension. In addition, these Python files can be opened as Jupyter Notebooks thanks to the `jupytext`_ extension. Documentarians writing new examples are encouraged to open a new Jupyter Lab session and write the example as a Jupyter Notebook. This way, the -documentarian can test the code and see the output in real-time. The created +documentarian can test the code and see the output in real time. The created Jupyter Notebook gets stored as a Python file automatically. Note that the examples are contained in its own repository, which you can find @@ -107,8 +106,8 @@ Finally, here are some tips for writing examples: description of what the example aims to determine. Write this section in an imperative form. -- Include an explanation with each code cell. In a Jupyter notebook, this - entails adding a markdown cell before each code cell. The explanations should +- Include an explanation with each code cell. In a Jupyter Notebook, this + entails adding a Markdown cell before each code cell. The explanations should be included before, not after, the corresponding code. .. _build-documentation: @@ -117,9 +116,8 @@ Build the documentation ======================= `Tox`_ is used for automating the build of the documentation. There are -different environments for cleaning the build, and building the documentation -in different formats such as HTML. , and running the tests. The following -environments are available: +different environments for cleaning the build, building the documentation +in different formats such as HTML, and running the tests. The following environments are available: diff --git a/doc/source/contribute/user.rst b/doc/source/contribute/user.rst index 97b597d0..5d08e329 100644 --- a/doc/source/contribute/user.rst +++ b/doc/source/contribute/user.rst @@ -1,5 +1,5 @@ -Contributing as a user -###################### +Contribute as a user +#################### Users can contribute in a variety of ways, such as reporting bugs, requesting new features, testing in-development features, starting discussions, answering @@ -38,7 +38,7 @@ questions, and sharing their work with the community. :link: start-a-discussion :link-type: ref - Want to discuss something? Start a discussion here. + Want to discuss something? Start or contribute to a discussion. .. grid-item-card:: :fa:`comment-dots` Answer questions :padding: 2 2 2 2 @@ -59,14 +59,14 @@ questions, and sharing their work with the community. Report bugs =========== -If you encounter a bug or an issue while using the project, please report it. -Your feedback helps to identify problems. +If you encounter a bug or an issue while using the project, report it. +Your feedback helps to identify problems and get them resolved. - Search the `PyWorkbench issues`_ to see if the issue has already been reported. -- Create a new issue if it hasn’t been reported. +- Create an issue if one doesn't already exist. - - Include a clear description of the problem. + - Include a clear description of the issue. - Provide steps to reproduce the issue. - Mention the version of the project you're using. - Include screenshots or logs if possible. @@ -77,8 +77,8 @@ Request a new feature ===================== Do you have an idea for a new feature or an improvement? Your suggestions are -welcome. You can request a new feature by creating an issue in the `PyWorkbench issues`_ -board. +welcome. You can request a new feature by creating an issue on the `PyWorkbench issues`_ +page. .. _test-a-new-feature: @@ -96,7 +96,7 @@ Start a discussion Complex topics may require a discussion. Whether you want to know how to use PyWorkbench for solving your specific problem or you have a suggestion for a new feature, a discussion is a good place to start. You can open a new discussion -in the `PyWorkbench discussions`_ section. +on the `PyWorkbench Discussions`_ page. .. _answer-questions: diff --git a/doc/source/index.rst b/doc/source/index.rst index 36383f8e..c1d622ce 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -52,7 +52,7 @@ with Workbench. :link-type: doc Download different assets related to PyWorkbench, such as - documentation, package wheelhouse, and related files. + documentation, the package wheelhouse, and related files. .. jinja:: main_toctree