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/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..7c044a20 --- /dev/null +++ b/doc/source/contribute.rst @@ -0,0 +1,45 @@ +Contribute +########## + +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 of conduct. + +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, 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 content. + + .. 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..dd296e79 --- /dev/null +++ b/doc/source/contribute/developer.rst @@ -0,0 +1,184 @@ +Contribute 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 + + 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 + + Clone the repository to download the copy to 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 to the project by running tests. + + +.. _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 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 + :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 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 on your machine. + +Clone the repository using SSH: + +.. code-block:: bash + + git clone git@github.com:ansys/pyworkbench + +.. note:: + + 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 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: + +.. code-block:: + + cd pyworkbench + +Then, create a new virtual environment named ``.venv`` to isolate your system's +Python environment: + +.. code-block:: text + + python -m venv .venv + +Finally, activate this environment: + +.. 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: + +.. 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. + +Install Tox: + +.. code-block:: text + + python -m pip install tox + +Verify the Tox installation by listing all the different environments +(automation rules) for PyWorkbench: + +.. code-block:: text + + tox list + +.. _run-tests: + +Run the tests +============= + +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. + +.. code-block:: text + + tox -e tests diff --git a/doc/source/contribute/documentarian.rst b/doc/source/contribute/documentarian.rst new file mode 100644 index 00000000..93ef6fad --- /dev/null +++ b/doc/source/contribute/documentarian.rst @@ -0,0 +1,139 @@ +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 + + 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 + + Write a new example to showcase the capabilities of PyWorkbench. + + .. 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 +=================== + +`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 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 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 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. + +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 causes 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, building the documentation +in different formats such as HTML, and running the tests. + +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..5d08e329 --- /dev/null +++ b/doc/source/contribute/user.rst @@ -0,0 +1,119 @@ +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 +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 or contribute to a discussion. + + .. 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, 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 an issue if one doesn't already exist. + + - 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. + +.. _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 on the `PyWorkbench issues`_ +page. + +.. _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 +on the `PyWorkbench Discussions`_ page. + +.. _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..c1d622ce 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 +.. jinja:: main_toctree - Learn how to install PyWorkbench and connect to Workbench. + .. grid:: 1 2 3 3 + :gutter: 1 2 3 3 + :padding: 1 2 3 3 - .. grid-item-card:: User guide :material-regular:`menu_book` - :link: user-guide - :link-type: doc + .. grid-item-card:: Getting started :material-regular:`directions_run` + :link: getting-started + :link-type: doc - Understand key concepts and approaches for using PyWorkbench with - the Workbench gRPC service. + Learn how to install PyWorkbench and connect to Workbench. -.. jinja:: main_toctree + .. grid-item-card:: User guide :material-regular:`menu_book` + :link: user-guide + :link-type: doc - {% if build_api or build_examples %} - .. grid:: 2 + 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 + {% 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. + 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 + {% 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. + 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, the 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/ diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 51569950..77f6ee8e 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 +(?i)documentarian +(?i)tox 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