diff --git a/.github/dependabot.yml b/.github/dependabot.yml index b73314023..145bc7af4 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,13 +1,17 @@ version: 2 updates: - - package-ecosystem: "pip" # See documentation for possible values - directory: "/" # Location of package manifests + - package-ecosystem: "pip" + directory: "/" insecure-external-code-execution: allow schedule: interval: "daily" labels: - "maintenance" - "dependencies" + assignees: + - "pyansys-ci-bot" + commit-message: + prefix: "build" - package-ecosystem: "github-actions" directory: "/" @@ -19,3 +23,7 @@ updates: - "pyansys-ci-bot" commit-message: prefix: "ci" + groups: + actions: + patterns: + - "*" 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/CONTRIBUTING.md b/CONTRIBUTING.md index 3c114f577..bb60004d6 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, 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]. + +[PyAnsys Developer's Guide]: https://dev.docs.pyansys.com/index.html +[Contributing]: https://sphinxdocs.ansys.com/version/dev/contribute.html diff --git a/doc/changelog.d/636.documentation.md b/doc/changelog.d/636.documentation.md new file mode 100644 index 000000000..a85be9130 --- /dev/null +++ b/doc/changelog.d/636.documentation.md @@ -0,0 +1 @@ +docs: add contribute section \ 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..bfc288baf --- /dev/null +++ b/doc/source/contribute.rst @@ -0,0 +1,33 @@ + +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. + + +.. 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 + :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..47f83eb06 --- /dev/null +++ b/doc/source/contribute/developer.rst @@ -0,0 +1,241 @@ +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 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. + +.. 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:: bash + + cd ansys-sphinx-theme + +Then, create a new virtual environment named ``.venv`` to isolate your system's +Python environment by running: + +.. code-block:: bash + + python -m venv .venv + +Finally, activate this environment by running: + +.. tab-set:: + + .. tab-item:: Windows + + .. tab-set:: + + .. tab-item:: CMD + + .. code-block:: bash + + .venv\Scripts\activate.bat + + .. tab-item:: PowerShell + + .. code-block:: bash + + .venv\Scripts\Activate.ps1 + + .. tab-item:: macOS/Linux/UNIX + + .. code-block:: bash + + source .venv/bin/activate + +Development mode +---------------- + +Now, install Ansys sphinx theme in editable mode by running: + +.. code-block:: bash + + 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:: bash + + >>> 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:: bash + + python -m pip install tox + +Finally, verify the installation by listing all the different environments +(automation rules) for Ansys Sphinx theme: + +.. code-block:: bash + + 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 + - usage + {% for environment in envs %} + {% set name, description = environment.split("->") %} + * - {{ name }} + - {{ description }} + - python -m tox -e {{ name }} + {% 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 + + +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:: + + python -m 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 diff --git a/doc/source/contribute/user.rst b/doc/source/contribute/user.rst new file mode 100644 index 000000000..11cfba0b5 --- /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 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 `Ansys sphinx theme 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 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 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/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..18c49acc8 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 issues: 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/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", diff --git a/tox.ini b/tox.ini index c5b347736..944ebf4ba 100644 --- a/tox.ini +++ b/tox.ini @@ -3,7 +3,8 @@ description = Default tox environments list envlist = code-style doc-style - doc-{links,html} + doc-{links,html,pdf,clean} + dist skip_missing_interpreters = true isolated_build = true isolated_build_env = build @@ -35,11 +36,26 @@ 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 = + 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}" + +[testenv:dist] +description = Checks project distribution +skip_install = true +deps = + build commands = - sphinx-build -d "{toxworkdir}/doc_doctree" doc/source "{toxinidir}/doc/_build/{env:BUILDER}" --color -v -b {env:BUILDER} -j auto -W --keep-going + python -m build {toxinidir} \ No newline at end of file