From fba63d451281c4bf5cd0e3c159149039a09c6433 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 12:37:19 +0100 Subject: [PATCH 01/19] docs: add contribute session --- .gitignore | 1 + doc/changelog.d/636.documentation.md | 1 + doc/source/conf.py | 11 ++ doc/source/contribute.rst | 15 ++ doc/source/contribute/developer.rst | 211 +++++++++++++++++++++++++++ doc/source/contribute/user.rst | 102 +++++++++++++ doc/source/index.rst | 1 + doc/source/links.rst | 9 +- tox.ini | 10 +- 9 files changed, 358 insertions(+), 3 deletions(-) create mode 100644 doc/changelog.d/636.documentation.md create mode 100644 doc/source/contribute.rst create mode 100644 doc/source/contribute/developer.rst create mode 100644 doc/source/contribute/user.rst diff --git a/.gitignore b/.gitignore index 8fa5cfae6..c68b289bb 100644 --- a/.gitignore +++ b/.gitignore @@ -28,6 +28,7 @@ share/python-wheels/ .installed.cfg *.egg MANIFEST +.DS_Store # PyInstaller # Usually these files are written by a python script from a template diff --git a/doc/changelog.d/636.documentation.md b/doc/changelog.d/636.documentation.md new file mode 100644 index 000000000..455acee06 --- /dev/null +++ b/doc/changelog.d/636.documentation.md @@ -0,0 +1 @@ +docs: add contribute session \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index fa8560bb5..66ca024d4 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -3,6 +3,7 @@ from datetime import datetime import os from pathlib import Path +import subprocess from typing import List from github import Github @@ -162,6 +163,11 @@ "version": f"v{version}" if not version.endswith("dev0") else "main", }, "pdf_guide": {"version": get_version_match(__version__)}, # noqa: E501 + "toxenvs": { + "envs": subprocess.run( + ["tox", "list", "-d", "-q"], capture_output=True, text=True + ).stdout.splitlines()[1:], + }, } @@ -297,3 +303,8 @@ def download_and_process_files(example_links: List[str]) -> List[str]: jinja_contexts["examples"] = {"inputs_examples": file_names} jinja_contexts["admonitions"] = {"inputs_admonitions": admonitions_links} + + +jinja_globals = { + "ANSYS_SPHINX_THEME_VERSION": version, +} diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst new file mode 100644 index 000000000..6cd1ceac8 --- /dev/null +++ b/doc/source/contribute.rst @@ -0,0 +1,15 @@ + +Contribute +########## + +Thank you for your interest in contributing to Ansys Sphinx theme! Contributions are welcome +to make the project better, whether it's fixing bugs, adding new features, or +improving documentation. Below are the guidelines to follow when contributing. + +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Contribute + + User + Developer \ No newline at end of file diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst new file mode 100644 index 000000000..9a4eea87c --- /dev/null +++ b/doc/source/contribute/developer.rst @@ -0,0 +1,211 @@ +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. + + +.. _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/ansys-sphinx-theme/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/ansys-sphinx-theme + +.. _install-for-developers: + +Install for developers +====================== + +Installing Ansys sphinx theme 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 ansys-sphinx-theme + +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 Ansys sphinx theme 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_sphinx_theme import __version__ + + + print(f"Ansys sphinx thenme version is {__version__}") + +.. jinja:: + + .. code-block:: text + + >>> Ansys sphinx theme version is {{ ANSYS_SPHINX_THEME_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 Ansys Sphinx theme: + +.. code-block:: text + + python -m tox list + +.. jinja:: toxenvs + + .. dropdown:: Default Tox environments + :animate: fade-in + :icon: three-bars + + .. list-table:: + :header-rows: 1 + :widths: auto + + * - Environment + - Description + {% for environment in envs %} + {% set name, description = environment.split("->") %} + * - {{ name }} + - {{ description }} + {% endfor %} + + +Adhere to code style +-------------------- + +Ansys Sphinx theme follows the PEP8 standard as outlined in +`PEP 8 `_ in +the *PyAnsys Developer's Guide* and implements style checking using +`pre-commit `_. + +To ensure your code meets minimum code styling standards, run these commands:: + + pip install pre-commit + pre-commit run --all-files + +or use tox as above:: + + tox -e code-style + +You can also install this as a pre-commit hook by running this command:: + + pre-commit install + +This way, it's not possible for you to push code that fails the style checks:: + + $ pre-commit install + $ git commit -am "added my cool feature" + ruff.....................................................................Passed + ruff-format..............................................................Passed + codespell................................................................Passed + prettier.................................................................Passed + check for merge conflicts................................................Passed + debug statements (python)................................................Passed + check yaml...............................................................Passed + trim trailing whitespace.................................................Passed + Validate GitHub Workflows................................................Passed + Add License Headers......................................................Passed \ No newline at end of file diff --git a/doc/source/contribute/user.rst b/doc/source/contribute/user.rst new file mode 100644 index 000000000..0eb96d5cb --- /dev/null +++ b/doc/source/contribute/user.rst @@ -0,0 +1,102 @@ +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:`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 `Ansys sphinx theme issue`_ 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 `Ansys sphinx theme issue`_ +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 Ansys Sphinx theme from the source code. + +.. _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 Ansys Sphinx theme to create something interesting, share it with the rest +of the community. You can share your work in the `Ansys sphinx theme issue`_. Include +a brief description of your work and any relevant links that others may find +useful. \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index b85d7ffc9..27283debd 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -54,3 +54,4 @@ are included in the theme to make documentation more appealing and user-friendly examples.rst {% endif %} changelog + contribute.rst diff --git a/doc/source/links.rst b/doc/source/links.rst index 0fdcbe5da..fde2ac6d8 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -12,6 +12,7 @@ .. _PyData_PyPI: https://pypi.org/project/pydata-sphinx-theme/ .. _Jinja2_PyPI: https://pypi.org/project/Jinja2/ .. _pip: https://pypi.org/project/pip/ +.. _Tox: https://tox.wiki/en/stable/ .. dependency docs links .. _sphinx_design_examples: https://github.com/executablebooks/sphinx-design/tree/furo-theme/docs/snippets/rst @@ -22,4 +23,10 @@ .. ansys_sphinx_theme links -.. _static_files: https://github.com/ansys/ansys-sphinx-theme/blob/main/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/logos/ \ No newline at end of file +.. _static_files: https://github.com/ansys/ansys-sphinx-theme/blob/main/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/logos/ +.. _Ansys sphinx theme issue: https://github.com/ansys/ansys-sphinx-theme/issues/ + + +.. other links +.. _git: https://git-scm.com/ +.. _configure SSH: https://docs.github.com/en/authentication/connecting-to-github-with-ssh \ No newline at end of file diff --git a/tox.ini b/tox.ini index c5b347736..95d539988 100644 --- a/tox.ini +++ b/tox.ini @@ -35,11 +35,17 @@ commands = vale sync --config="{toxinidir}/doc/.vale.ini" vale --config="{toxinidir}/doc/.vale.ini" "{toxinidir}/doc" -[testenv:doc-{links,html}] +[testenv:doc-{clean,links,html,pdf}] description = Checks documentation links and pages generates properly +allowlist_externals = + pdflatex extras = doc setenv = + SOURCE_DIR = doc/source + BUILD_DIR = doc/_build links: BUILDER = linkcheck html: BUILDER = html + pdf: BUILDER = latex + links,html,pdf: BUILDER_OPTS = --color -v -j auto -W --keep-going commands = - sphinx-build -d "{toxworkdir}/doc_doctree" doc/source "{toxinidir}/doc/_build/{env:BUILDER}" --color -v -b {env:BUILDER} -j auto -W --keep-going + links,html,pdf: sphinx-build -d "{toxworkdir}/doc_doctree" {env:SOURCE_DIR} "{toxinidir}/{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} -b {env:BUILDER} From 9cc31742656317614c17803358cb25d2b08eaf8a Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 12:45:40 +0100 Subject: [PATCH 02/19] docs: add build docs --- doc/source/contribute/developer.rst | 32 ++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst index 9a4eea87c..4d1bd4232 100644 --- a/doc/source/contribute/developer.rst +++ b/doc/source/contribute/developer.rst @@ -208,4 +208,34 @@ This way, it's not possible for you to push code that fails the style checks:: check yaml...............................................................Passed trim trailing whitespace.................................................Passed Validate GitHub Workflows................................................Passed - Add License Headers......................................................Passed \ No newline at end of file + Add License Headers......................................................Passed + + +Build the documentation +---------------------- + +To build documentation locally, you can either use tox as mentioned above or +run the following commands: + +1. Install the required dependencies by running:: + + pip install -e .[doc] + +2. Build the documentation by running:: + + # On Linux or macOS + make -C doc/ html + + # On Windows + doc\make.bat html + +3. The documentation is built in the ``doc/_build/html`` directory. Open the + ``index.html`` file in your browser to view the documentation. + +You can clean the build directory by running:: + + # On Linux or macOS + make -C doc/ clean + + # On Windows + doc\make.bat clean From 10047744887f6d81dcf1ef2b5de461bf3d0bea03 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 12:48:42 +0100 Subject: [PATCH 03/19] docs: add contribute page --- doc/source/contribute.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst index 6cd1ceac8..bfc288baf 100644 --- a/doc/source/contribute.rst +++ b/doc/source/contribute.rst @@ -6,6 +6,24 @@ Thank you for your interest in contributing to Ansys Sphinx theme! Contributions to make the project better, whether it's fixing bugs, adding new features, or improving documentation. Below are the guidelines to follow when contributing. + +.. grid:: + :gutter: 1 2 3 3 + :padding: 1 2 3 3 + + .. grid-item-card:: :fa:`user` User + :link: contribute/user + :link-type: doc + + Learn how to contribute as a user. + + .. grid-item-card:: :fa:`code-fork` Developer + :link: contribute/developer + :link-type: doc + + Learn how to contribute as a developer. + + .. toctree:: :hidden: :maxdepth: 1 From 902b8142a1c4f86f911ce17e81b75d9254f6131e Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 13:20:34 +0100 Subject: [PATCH 04/19] docs: add dependency --- doc/source/contribute/developer.rst | 4 ++-- pyproject.toml | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst index 4d1bd4232..2777f9ce2 100644 --- a/doc/source/contribute/developer.rst +++ b/doc/source/contribute/developer.rst @@ -136,8 +136,8 @@ Verify the installation by checking the version of the library: >>> Ansys sphinx theme version is {{ ANSYS_SPHINX_THEME_VERSION }} -Install Tox ------------ +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 diff --git a/pyproject.toml b/pyproject.toml index 84c8f36b7..8b18374ed 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,6 +55,7 @@ doc = [ "sphinx-gallery==0.19.0", "sphinx-jinja==2.0.2", "sphinx-notfound-page==1.1.0", + "tox==4.24.1", ] changelog = [ "PyYAML==6.0.2", From d78ea42d59ebeca8d497c6272b188be9cd8357ef Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 13:25:34 +0100 Subject: [PATCH 05/19] docs: add contribute --- CONTRIBUTING.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c114f577..93e29dbdb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,16 @@ # Contributing -If you are interested in contributing to our project, please make sure to review -our contribution guidelines, which are specified in the -[PyAnsys Developer's Documentation - Contributing](https://dev.docs.pyansys.com/how-to/contributing.html) page. This document -outlines the process for submitting issues, proposing changes, and making pull -requests to our codebase. Following these guidelines will help ensure that your -contributions are properly integrated and reviewed, and will help maintain the -overall quality and consistency of the project. Thank you for your interest in -contributing to our community. +We absolutely welcome any code contributions and we hope that this +guide will facilitate an understanding of the Ansys sphinx theme code +repository. It is important to note that while the Ansys sphinx theme software +package is maintained by ANSYS and any submissions will be reviewed +thoroughly before merging, we still seek to foster a community that can +support user questions and develop new features to make this software +a useful tool for all users. As such, we welcome and encourage any +questions or submissions to this repository. + +For contributing to this project, please refer to the [PyAnsys Developer's Guide]. +Further information about contributing to Ansys sphinx theme can be found in [Contributing]. + +[PyAnsys Developer's Guide]: https://dev.docs.pyansys.com/index.html +[Contributing]: https://sphinxdocs.ansys.com/version/dev/contributing.html From fa9ef1f9b3bb14bf81f75f19e5faa8cc57658171 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 13:26:07 +0100 Subject: [PATCH 06/19] docs: add contribute link --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 93e29dbdb..4eec687ff 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,4 +13,4 @@ For contributing to this project, please refer to the [PyAnsys Developer's Guide Further information about contributing to Ansys sphinx theme can be found in [Contributing]. [PyAnsys Developer's Guide]: https://dev.docs.pyansys.com/index.html -[Contributing]: https://sphinxdocs.ansys.com/version/dev/contributing.html +[Contributing]: https://sphinxdocs.ansys.com/version/dev/contribute.html From 2ca6ade6071dbd28db1f39e075166f26c959391c Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Mon, 3 Mar 2025 12:27:24 +0000 Subject: [PATCH 07/19] chore: adding changelog file 636.documentation.md [dependabot-skip] --- doc/changelog.d/636.documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/changelog.d/636.documentation.md b/doc/changelog.d/636.documentation.md index 455acee06..a85be9130 100644 --- a/doc/changelog.d/636.documentation.md +++ b/doc/changelog.d/636.documentation.md @@ -1 +1 @@ -docs: add contribute session \ No newline at end of file +docs: add contribute section \ No newline at end of file From d432baf5c3fae8a4cadadbf3e1b71d26c6618c8d Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 13:29:24 +0100 Subject: [PATCH 08/19] docs: update dependabot --- .github/dependabot.yml | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index b73314023..c9066d326 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,13 +1,20 @@ version: 2 updates: - - package-ecosystem: "pip" # See documentation for possible values - directory: "/" # Location of package manifests - insecure-external-code-execution: allow + - package-ecosystem: "pip" + directory: "/" schedule: interval: "daily" labels: - "maintenance" - "dependencies" + assignees: + - "pyansys-ci-bot" + commit-message: + prefix: "build" + group: + dependencies: + patterns: + - "*" - package-ecosystem: "github-actions" directory: "/" @@ -19,3 +26,7 @@ updates: - "pyansys-ci-bot" commit-message: prefix: "ci" + groups: + actions: + patterns: + - "*" From 19fb17f31ae6e1fb151c2495699b9a761b6c5ee4 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 13:30:46 +0100 Subject: [PATCH 09/19] docs: update dependabot --- .github/dependabot.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index c9066d326..5aef5887f 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -11,7 +11,7 @@ updates: - "pyansys-ci-bot" commit-message: prefix: "build" - group: + groups: dependencies: patterns: - "*" From 1b5d1cdbc3c1e2dcf637709037d388bb84799366 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 13:32:47 +0100 Subject: [PATCH 10/19] docs: update dependabot --- .github/dependabot.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 5aef5887f..145bc7af4 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -2,6 +2,7 @@ version: 2 updates: - package-ecosystem: "pip" directory: "/" + insecure-external-code-execution: allow schedule: interval: "daily" labels: @@ -11,10 +12,6 @@ updates: - "pyansys-ci-bot" commit-message: prefix: "build" - groups: - dependencies: - patterns: - - "*" - package-ecosystem: "github-actions" directory: "/" From 76e32264f21713b45f006d22540df72504e84ce2 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 13:35:10 +0100 Subject: [PATCH 11/19] docs: add tox usage --- doc/source/contribute/developer.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst index 2777f9ce2..f3984baa7 100644 --- a/doc/source/contribute/developer.rst +++ b/doc/source/contribute/developer.rst @@ -167,10 +167,12 @@ Finally, verify the installation by listing all the different environments * - Environment - Description + - usage {% for environment in envs %} {% set name, description = environment.split("->") %} * - {{ name }} - {{ description }} + - python -m tox -e {{ name }} {% endfor %} From dfc6ceec7bb27ac850b10879feb135f85edaba64 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 14:07:56 +0100 Subject: [PATCH 12/19] fix: docs error --- doc/source/contribute/developer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst index f3984baa7..6d9134a5d 100644 --- a/doc/source/contribute/developer.rst +++ b/doc/source/contribute/developer.rst @@ -214,7 +214,7 @@ This way, it's not possible for you to push code that fails the style checks:: Build the documentation ----------------------- +----------------------- To build documentation locally, you can either use tox as mentioned above or run the following commands: From 03ee2e6be117f53d0860638a88d82f735f26dfd2 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 14:16:42 +0100 Subject: [PATCH 13/19] fix: docs cleanup --- doc/source/contribute/developer.rst | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst index 6d9134a5d..d392a1633 100644 --- a/doc/source/contribute/developer.rst +++ b/doc/source/contribute/developer.rst @@ -74,14 +74,14 @@ Virtual environment Start by navigating to the project's root directory by running: -.. code-block:: +.. code-block:: bash cd ansys-sphinx-theme Then, create a new virtual environment named ``.venv`` to isolate your system's Python environment by running: -.. code-block:: text +.. code-block:: bash python -m venv .venv @@ -95,19 +95,19 @@ Finally, activate this environment by running: .. tab-item:: CMD - .. code-block:: text + .. code-block:: bash .venv\Scripts\activate.bat .. tab-item:: PowerShell - .. code-block:: text + .. code-block:: bash .venv\Scripts\Activate.ps1 .. tab-item:: macOS/Linux/UNIX - .. code-block:: text + .. code-block:: bash source .venv/bin/activate @@ -116,7 +116,7 @@ Development mode Now, install Ansys sphinx theme in editable mode by running: -.. code-block:: text +.. code-block:: bash python -m pip install --editable . @@ -126,13 +126,11 @@ Verify the installation by checking the version of the library: .. code-block:: python from ansys_sphinx_theme import __version__ - - print(f"Ansys sphinx thenme version is {__version__}") .. jinja:: - .. code-block:: text + .. code-block:: bash >>> Ansys sphinx theme version is {{ ANSYS_SPHINX_THEME_VERSION }} @@ -144,14 +142,14 @@ 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 +.. code-block:: bash python -m pip install tox Finally, verify the installation by listing all the different environments (automation rules) for Ansys Sphinx theme: -.. code-block:: text +.. code-block:: bash python -m tox list From efaa1301464ab2b3dfa9d48b59d8fe95b62021f2 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 14:23:45 +0100 Subject: [PATCH 14/19] fix: tox clean command --- tox.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/tox.ini b/tox.ini index 95d539988..b4013052e 100644 --- a/tox.ini +++ b/tox.ini @@ -49,3 +49,4 @@ setenv = links,html,pdf: BUILDER_OPTS = --color -v -j auto -W --keep-going commands = links,html,pdf: sphinx-build -d "{toxworkdir}/doc_doctree" {env:SOURCE_DIR} "{toxinidir}/{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} -b {env:BUILDER} + clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}" \ No newline at end of file From ecc4e7c13b5ecf9b2ba0c7900bcec9e0cfa0d1a8 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 14:24:07 +0100 Subject: [PATCH 15/19] fix: tox clean command --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index b4013052e..eda74d58b 100644 --- a/tox.ini +++ b/tox.ini @@ -3,7 +3,7 @@ description = Default tox environments list envlist = code-style doc-style - doc-{links,html} + doc-{links,html,pdf,clean} skip_missing_interpreters = true isolated_build = true isolated_build_env = build From b7251c64e784c4307d2872a5b7ea6406ba77c1eb Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 14:25:51 +0100 Subject: [PATCH 16/19] docs: add dist tox commad --- tox.ini | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index eda74d58b..944ebf4ba 100644 --- a/tox.ini +++ b/tox.ini @@ -4,6 +4,7 @@ envlist = code-style doc-style doc-{links,html,pdf,clean} + dist skip_missing_interpreters = true isolated_build = true isolated_build_env = build @@ -49,4 +50,12 @@ setenv = links,html,pdf: BUILDER_OPTS = --color -v -j auto -W --keep-going commands = links,html,pdf: sphinx-build -d "{toxworkdir}/doc_doctree" {env:SOURCE_DIR} "{toxinidir}/{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} -b {env:BUILDER} - clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}" \ No newline at end of file + clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}" + +[testenv:dist] +description = Checks project distribution +skip_install = true +deps = + build +commands = + python -m build {toxinidir} \ No newline at end of file From 270f4eb55fd16ba05f5f03fca43c8fde97805c50 Mon Sep 17 00:00:00 2001 From: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com> Date: Mon, 3 Mar 2025 16:14:03 +0100 Subject: [PATCH 17/19] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jorge Martínez <28702884+jorgepiloto@users.noreply.github.com> --- CONTRIBUTING.md | 8 ++++---- doc/source/contribute/developer.rst | 4 ++-- doc/source/contribute/user.rst | 4 ++-- doc/source/links.rst | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4eec687ff..bb60004d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,16 +1,16 @@ # Contributing We absolutely welcome any code contributions and we hope that this -guide will facilitate an understanding of the Ansys sphinx theme code -repository. It is important to note that while the Ansys sphinx theme software -package is maintained by ANSYS and any submissions will be reviewed +guide will facilitate an understanding of the Ansys Sphinx theme code +repository. It is important to note that while the Ansys Sphinx theme software +package is maintained by ANSYS, Inc. and any submissions will be reviewed thoroughly before merging, we still seek to foster a community that can support user questions and develop new features to make this software a useful tool for all users. As such, we welcome and encourage any questions or submissions to this repository. For contributing to this project, please refer to the [PyAnsys Developer's Guide]. -Further information about contributing to Ansys sphinx theme can be found in [Contributing]. +Further information about contributing to Ansys Sphinx theme can be found in [Contributing]. [PyAnsys Developer's Guide]: https://dev.docs.pyansys.com/index.html [Contributing]: https://sphinxdocs.ansys.com/version/dev/contribute.html diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst index d392a1633..59715a4ea 100644 --- a/doc/source/contribute/developer.rst +++ b/doc/source/contribute/developer.rst @@ -214,12 +214,12 @@ This way, it's not possible for you to push code that fails the style checks:: Build the documentation ----------------------- -To build documentation locally, you can either use tox as mentioned above or +To build documentation locally, you can either use Tox as mentioned above or run the following commands: 1. Install the required dependencies by running:: - pip install -e .[doc] + python -m pip install -e .[doc] 2. Build the documentation by running:: diff --git a/doc/source/contribute/user.rst b/doc/source/contribute/user.rst index 0eb96d5cb..a6bd77f07 100644 --- a/doc/source/contribute/user.rst +++ b/doc/source/contribute/user.rst @@ -55,7 +55,7 @@ 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 `Ansys sphinx theme issue`_ to see if the issue has already been reported. +- Search the `Ansys Sphinx theme issues`_ to see if the issue has already been reported. - Create a new issue if it hasn’t been reported. @@ -97,6 +97,6 @@ Share your work =============== If you have used Ansys Sphinx theme to create something interesting, share it with the rest -of the community. You can share your work in the `Ansys sphinx theme issue`_. Include +of the community. You can share your work in the `Ansys Sphinx theme issues`_. Include a brief description of your work and any relevant links that others may find useful. \ No newline at end of file diff --git a/doc/source/links.rst b/doc/source/links.rst index fde2ac6d8..18c49acc8 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -24,7 +24,7 @@ .. ansys_sphinx_theme links .. _static_files: https://github.com/ansys/ansys-sphinx-theme/blob/main/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/logos/ -.. _Ansys sphinx theme issue: https://github.com/ansys/ansys-sphinx-theme/issues/ +.. _Ansys Sphinx theme issues: https://github.com/ansys/ansys-sphinx-theme/issues/ .. other links From 907f8a2dcc7aee6dff23f8fc03c288410cf79972 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Mon, 3 Mar 2025 16:23:44 +0100 Subject: [PATCH 18/19] docs: fix links --- doc/source/contribute/user.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contribute/user.rst b/doc/source/contribute/user.rst index a6bd77f07..11cfba0b5 100644 --- a/doc/source/contribute/user.rst +++ b/doc/source/contribute/user.rst @@ -70,7 +70,7 @@ 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 `Ansys sphinx theme issue`_ +welcome. You can request a new feature by creating an issue in the `Ansys sphinx theme issues`_ board. .. _test-a-new-feature: From d91eaea78257b3cc43ca2467d00666a8da393040 Mon Sep 17 00:00:00 2001 From: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com> Date: Mon, 3 Mar 2025 16:24:00 +0100 Subject: [PATCH 19/19] Update doc/source/contribute/developer.rst Co-authored-by: Maxime Rey <87315832+MaxJPRey@users.noreply.github.com> --- doc/source/contribute/developer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst index 59715a4ea..47f83eb06 100644 --- a/doc/source/contribute/developer.rst +++ b/doc/source/contribute/developer.rst @@ -30,7 +30,7 @@ Contributing as a developer Fork the repository =================== -Forking the repository is the first step to contributing to the project. This +Forking the repository is the first step for 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.