docs(contributing): basic layout #199

jorgepiloto · 2025-03-10T08:26:27Z

This pull-request includes the Contribute section for this project. Three basic sections are included:

Preview for each section:

github-actions · 2025-03-10T08:27:29Z

The towncrier template has been successfully rewritten with the default template.
Please ensure that sphinx-design is included as a dependency in your project's documentation requirements.
Additionally, add sphinx-design to the extensions list in your conf.py file.
For more information, please refer to the migration guide at:
https://actions.docs.ansys.com/version/stable/migrations/index.html#migration-guide

wiz-inc-572fc38784 · 2025-03-10T08:39:04Z

Wiz Scan Summary

Scanner	Findings
Vulnerabilities
Sensitive Data	1
Secrets
IaC Misconfigurations

Total	1

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try using Wiz Code VS Code Extension.

vnamdeo

Looks good.

doc/source/contribute.rst

doc/source/contribute/developer.rst

PipKat · 2025-03-11T19:57:32Z

doc/source/contribute/developer.rst

+
+.. note::
+
+    If you are an Ansys employee, you can skip this step.


What about the instructions for external contributors?

@jorgepiloto I can see now that my comment doesn't really make sense. The "Fork the repository" step doesn't have to be completed by Ansys employees, and external contributors can refer to GitHub resources or the PyAnsys dev guide for forking instructions. Should we say something to this effect though--or is it just obvious to developers? If so, just resolve this comment!

doc/source/contribute/developer.rst

PipKat · 2025-03-11T20:45:38Z

doc/source/contribute.rst

@@ -0,0 +1,45 @@
+Contribute


@jorgepiloto So much of this content seems like what we talked about as part of the url_include and snippet approach. Will it eventually be implemented as we planned? Your examples also sound rather PySDK-specific, not Workbench specific or generic enough to be part of a template. Should we consider that?

Hi @PipKat, having this as a template would be the best. By using Tox, like this project does, the commands are the same for every project. This allows the content to be "templatized".

PipKat

@jorgepiloto Feedback for your consideration.

Co-authored-by: Kathy Pippert <[email protected]>

PipKat · 2025-04-10T13:27:24Z

doc/source/contribute.rst

+    This project adheres to the `Contributor Covenant Code of Conduct`_. By
+    participating, you agree to uphold this code of conduct.
+
+Start by selecting your role in the project:


Suggested change

Start by selecting your role in the project:

Overall guidance on contributing to a PyAnsys repository appears in

`Contribute <https://dev.docs.pyansys.com/how-to/contributing.html>`_

in the *PyAnsys developer's guide*. Ensure that you are thoroughly familiar

with this guide before attempting to contribute to PyWorkbench.

The following contribution information is specific to PyWorkbench. Start by

selecting your role in the project:

Adding content to make this Contribute topic and the one for PyHeart consistent.

PipKat · 2025-04-10T13:33:48Z

doc/source/contribute/developer.rst

+        :link-type: ref
+
+        Verify your changes to the project by running tests.
+


@jorgepiloto I see PyHeart has two additional sections: Code style compliance and Run the CI/CD pipelines. Do you possibly want to add this type of content to this library?

PipKat · 2025-04-10T13:42:12Z

doc/source/contribute/documentarian.rst

+Contributing as a documentarian
+###############################


Suggested change

Contributing as a documentarian

###############################

Contribute as a documentarian

#############################

PipKat · 2025-04-10T13:52:51Z

doc/source/contribute/developer.rst

+
+.. note::
+
+    If you are not an Ansys employee, you must fork the repository and


Suggested change

If you are not an Ansys employee, you must fork the repository and

If you are not an Ansys employee, you must :ref:`fork the repository <fork-the-repository> and

PipKat · 2025-04-10T13:55:56Z

doc/source/contribute/developer.rst

+
+    .. code-block:: text
+
+       >>> pyworkbench version is {{ PYWORKBENCH_VERSION }}


Suggested change

>>> pyworkbench version is {{ PYWORKBENCH_VERSION }}

>>> PyWorkbench version is {{ PYWORKBENCH_VERSION }}.

PipKat · 2025-04-10T13:58:04Z

doc/source/contribute/developer.rst

+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.


Suggested change

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.

automation tool. The main advantage of Tox is that it eases routine tasks like project

testing, documentation generation, and wheel building in separate and isolated Python

virtual environments.

I replaced with the wording that was in PyHeart as it sounded better!

PipKat · 2025-04-10T13:59:27Z

doc/source/contribute/developer.rst

+
+.. code-block:: text
+
+    tox list


Should this be python -m tox list like in the PyHeart doc?

PipKat · 2025-04-10T14:05:53Z

doc/source/contribute/developer.rst

+Once you have made your changes, you can run the tests to verify that your
+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.


Not sure if we can use this instead--to match PyAnsys Heart wording:

PyWorkbench tests support different markers
to allow testing with or without coverage (and against specific Python versions).
These markers are associated with dedicated Tox environments.

PipKat · 2025-04-10T14:21:18Z

doc/source/contribute/developer.rst

+
+.. button-link:: https://github.com/ansys/pyworkbench/fork
+    :color: primary
+    :align: center


Suggested change

:align: center

:align: left

We should be avoiding center alignment.

PipKat · 2025-04-10T14:27:24Z

doc/source/contribute/documentarian.rst

+        :link: build-documentation
+        :link-type: ref
+
+        Render the documentation to see your changes reflected.


Suggested change

Render the documentation to see your changes reflected.

Build the documentation to see your changes rendered.

PipKat · 2025-04-10T14:29:53Z

doc/source/contribute/documentarian.rst

+
+`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 <Examples>`, use a mix of `Markdown`_ and Python. If


Suggested change

:ref:`examples <Examples>`, use a mix of `Markdown`_ and Python. If

:ref:`examples <Examples>`, use a mix of `Markdown`_ and Python files. If

PipKat · 2025-04-10T14:34:12Z

doc/source/contribute/documentarian.rst

+`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 <Examples>`, use a mix of `Markdown`_ and Python. If
+you are interested in writing examples, see :ref:`writing examples <write-examples>`.


Suggested change

you are interested in writing examples, see :ref:`writing examples <write-examples>`.

you are interested in writing examples, see :ref:`write-examples`.

We just want to use the section title here.

PipKat · 2025-04-10T14:35:02Z

doc/source/contribute/documentarian.rst

+The documentation is located in the ``doc/source`` directory. The landing page
+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


Suggested change

``doc/source/_static/`` folder contains various assets like images, and CSS

``doc/source/_static/`` directory contains various assets like images and CSS

PipKat · 2025-04-10T14:35:45Z

doc/source/contribute/documentarian.rst

+
+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


Suggested change

``doc/source/contribute/documentarian.rst``file renders as

``doc/source/contribute/documentarian.rst`` file renders as the

PipKat · 2025-04-10T14:36:40Z

doc/source/contribute/documentarian.rst

+``doc/source/contribute/documentarian.rst``file renders as
+``https://workbench.docs.pyansys.com/contribute/documentarian`` URL.
+
+Thus, if you create a file, it important to follow these rules:


Suggested change

Thus, if you create a file, it important to follow these rules:

Thus, if you create a file, it is important to follow these rules:

PipKat · 2025-04-10T14:37:49Z

doc/source/contribute/documentarian.rst

+- 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.


Suggested change

- Play smart with the hierarchy of the files and directories.

- Logically organize the hierarchy of the files and directories.

PipKat · 2025-04-10T14:38:36Z

doc/source/contribute/documentarian.rst

+- Use hyphens to separate words.
+- Play smart with the hierarchy of the files and directories.
+
+You must include all files in a table of contents. No orphan files are


Suggested change

You must include all files in a table of contents. No orphan files are

You must include all files in the table of contents. Sphinx does not permit any orphan files.

PipKat · 2025-04-10T14:39:03Z

doc/source/contribute/documentarian.rst

+- Play smart with the hierarchy of the files and directories.
+
+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


Suggested change

permitted. If a file is not included in the table of contents, Sphinx raises a

If you do not include a file in the table of contents, Sphinx raises a

PipKat · 2025-04-10T14:40:45Z

doc/source/contribute/documentarian.rst

+permitted. If a file is not included in the table of contents, Sphinx raises a
+warning that causes the build to fail.
+
+A table of contents can be declared using a directive like this:


Suggested change

A table of contents can be declared using a directive like this:

You declare the table of contents using a directive like this:

PipKat · 2025-04-10T16:16:42Z

doc/source/contribute/documentarian.rst

+
+`Tox`_ is used for automating the build of the documentation. There are
+different environments for cleaning the build, building the documentation
+in different formats such as HTML, and running the tests.


Suggested change

in different formats such as HTML, and running the tests.

in different formats such as HTML and PDF, and running the tests.

PipKat · 2025-04-10T16:21:46Z

doc/source/contribute/user.rst

+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.


Suggested change

- Search the `PyWorkbench issues`_ to see if the issue has already been reported.

- Search the `PyWorkbench issues`_ page to see if the issue has already been reported.

PipKat · 2025-04-10T16:33:02Z

doc/source/contribute/user.rst

+===============
+
+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


Suggested change

of the community. You can share your work in the `PyWorkbench discussions`_. Include

of the community. You can share your work on the `PyWorkbench discussions`_ page. Include

PipKat · 2025-04-10T16:33:37Z

doc/source/contribute/user.rst

+
+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


Suggested change

a brief description of your work and any relevant links that others may find

a brief description of your work and any relevant links that others might find

PipKat · 2025-04-14T15:53:53Z

doc/source/contribute/user.rst

+Test a new feature
+==================
+
+It is possible to test a new feature before it is officially released. To do


Suggested change

It is possible to test a new feature before it is officially released. To do

You can test a new feature before it is officially released. To do

PipKat · 2025-04-14T15:58:28Z

doc/source/contribute/user.rst

+Start a discussion
+==================
+
+Complex topics may require a discussion. Whether you want to know how to use


Suggested change

Complex topics may require a discussion. Whether you want to know how to use

Complex topics might require a discussion. Whether you want to know how to use

franknli · 2025-05-07T16:23:32Z

@jorgepiloto Is this PR ready to be merged?

docs(contributing): basic layout

f23c076

github-actions bot added the documentation Improvements or additions to documentation label Mar 10, 2025

pyansys-ci-bot and others added 4 commits March 10, 2025 08:27

chore: adding changelog file 199.documentation.md [dependabot-skip]

da0774c

fix(tox): test command

aeefe64

fix(style): code

49af9cf

fix(style): doc

31a1f6b

jorgepiloto added 2 commits March 10, 2025 09:42

fix(style): doc

e06d2c5

fix(style): doc

4d47f24

jorgepiloto marked this pull request as ready for review March 10, 2025 08:45

jorgepiloto requested review from PipKat and a team as code owners March 10, 2025 08:45

jorgepiloto requested a review from vnamdeo March 10, 2025 08:46

Merge branch 'main' into docs/contributing

9ea1964

franknli approved these changes Mar 10, 2025

View reviewed changes

vnamdeo approved these changes Mar 11, 2025

View reviewed changes